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Introduction 



This ViewPoint Programmer's Manual is written for programmers who are developing 
applications to run on ViewPoint software. ViewPoint's open architecture philosophy 
allows applications to be developed easily. 

You will find this manual useful only if you are already a Mesa programmer. You should 
have completed the Mesa Course and be familiar with the contents of the XDE User's 
Guide (610E00140) and the Mesa Language Manual (610E00170). You should also be 
familiar with the facilities described in the Pilot Programmer's Manual (610E00160) and 
the Filing Programmer's Manual contained in the Services Programmer's Guide 
(610E00180). 

The ViewPoint Programmer's Manual gives you the information you will need to 
implement the user interface of an application that runs on ViewPoint. This includes how 
to: 

• Represent applications as icons. 

• Interact with the mouse and keyboard to process the user's instructions. 

• Create folder-like containers. 

• Create property sheets. 

• Create menus. 

• Paint pictures and text on the display. 

• Create programmable keyboards. 

• Represent and manipulate multinational text. 

It does not provide you with Mesa, Pilot, or Services-specific information. 
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1.1 Document Structure 

This introductory chapter describes the physical manual itself, how it is organized, who 
should read it, how it should be read, and why. Chapter 2, Overview, describes ViewPoint 
and discuss its history and overall design. 

Chapter 3, The Programmer's Guide, tells how to use the ViewPoint interfaces. It 
describes concepts essential to understanding ViewPoint and describes the facilities that 
are available. The most common interfaces are briefly discussed and grouped b> 
application. All of the ViewPoint interfaces, with a short summary, are listed 
alphabetically at the end of the chapter. 

The individual interface chapters are arranged alphabetically in Chapters 4 through 59. 
These chapters give detailed descriptions of the interfaces that ViewPoint provides. Each 
interface chapter begins with an overview that e.xplains the concepts behind the interface 
and the important data types that it manipulates. The second section of each chapter 
describes the actual items of the Mesa interface and groups them by function. The third 
section explains typical ways of using the interface and often contains programming 
examples. The fourth section is the index of interface items. Within an interface chapter, 
the items of the broadest interest are presented first; more specialized items follow later. 

Appendix A presents the system TIP Tables, references are in Appendix B, Appendix C 
contains a list of well-known atoms, and Appendix D contains a listing of public symbols. 

1.2 Getting Started 

Chapters I, 2, and 3 of the ViewPoint Programmer's Manual should be read in order 
Within Chapter 3, you will sometimes be guided to various sections in task-relative rather 
than page-relative order. Chapters 4 through 59 (the interface chapters) can be read in 
any order, depending on your need. 



Overview 



2.1 What Is Viewpoint? 

• ViewPoint is a collection of facilities for writing application programs that run on a 
personal workstation with a high-resolution bitmap display. It supports an open-ended 
collection of applications, providing a framework and a set of rules that allow these 
independent applications to be integrated. It has an advanced user interface that also 
allows applications to be easily adapted for users in other countries. 

Throughout this document, the term user describes a person who interacts with the 
applications built on ViewPoint via the mouse and keyboard. Programs cannot predict or 
control user actions. The term c/ieni describes programs that use the facilities described in 
this document. The client may act as a result of some user action, but the behavior of the 
client is the result of a program and under control of its implementor. 

2.1.1 User Abstractions 

ViewPoint uses several abstractions that are part of the advanced user interface pioneered 
by the Star Workstation; 

• Icons and Desktop. Icons that represent objects on a desktop are one basic abstraction. 
These objects can represent either functions or data. Data icons, such as a document, 
represent objects on which actions can be performed. Function icons, such as a printer, 
represent objects that perform actions. In the metaphor, they are on the desktop that 
also serves as the background for their display. With ViewPoint, clients may create 
new icons that provide additional functions within the desktop metaphor. 

• Windows. Windows are rectangular areas on the screen that display the contents of an 
icon when it is opened. Each window has a header containing the name of the 
window's icon and a set of commands. The window also contains scroll bars that scroll 
the contents of the window vertically and horizontally. 

• Property Sheets. Property sheets are displayed forms that show the properties of an 
object. They contain several types of parameters, including state parameters, which 
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may be on or off; choice parameters, which have a set of mutually exclusive values; ^filllk 
and text parameters. 

• Selection. The selection is an object or body of data identified by the user. It is the 
target of user actions; there can be only one selection at any one time. It can be a string 
of text that the user may then delete, copy, or change the properties of. It can be an 
icon on the desktop that is moved to a printer icon for printing or opened to display its 
contents. In general, it can be almost any piece of data that can be represented on the 
screen. 

2.1.2 Client Abstractions 

To implement the above user abstractions and to provide some building blocks for 
developing applications, ViewPoint uses several client abstractions: 

• Containee and StarDesktop Containee is an application registration facility that 
associates an application with a file type. Registering an application consists of 
providing procedures that paint iconic pictures and perform various operations. 
StarDesktop, using the desktop metaphor, displays the desktop window and iconic 
pictures for each file found in a particular directory. 

• Client Windows. The client window abstraction is more primitive than the user 
window abstraction. The client window abstraction serves to isolate applicat ions from 
the physical display and each other. A window can be thought of as a quarter of an 
infinite plane. Within that space, the client is called upon to display the contents of the 
window without regard to any other applications' windows. Windows may be linked to 
form a tree structure. A user's window is typically composed of a number of small 
client windows-one for the header, one for each scroll bar, and so forth. 

• Menus. Menus are sequences of named commands, each consisting of a text name and 
a procedure. Menus may be displayed to the user in several forms, such as in a pop-up 
menu or as window shell header commands (see below). 



• Window Shells. The user window abstraction is implemented by window shells. They 
provide the header, scroll bars, and body windows. The body windows are windows the 
client uses to display the content of an application. The commands in the header are 
menus. 

• Form Windows. Form windows are the client abstraction that provides the basis for 
the user property sheet. Form windows allow form items in a window to be created and 
manipulated. There are several types of items: boolean items, choice items, text items, 
numeric text items, command items, form and window items. Window items allow the 
client to implement its own type of item. The property sheet user abstraction is 
implemented by putting a form window inside a window shell. 
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• Container Windows, Container windows implement a window that contains a list of 
items. Clients supply the source of items and the container window handles that 
display the contents in a window and interact with the user. 



• Selection. The client selection abstraction is a framework in which a client can 
manifest itself as the holder of the user's current selection while other clients 
interrogate the selection and request that it be converted to a variety of data types. 
ViewPoint defines several selection conversion types, but the selection framework 
allows clients to define additional conversion types The selection is the principal 
means by which information is transferred between different applications. 



2.1.3 System Structure 



Viewpoint's architecture contains a small set of public interfaces that provide the basic 
facilities for building workstation applications. Facilities are included in ViewPoint for 
several reasons. Some facilities implement system-wide features, such as the window 
package. If several applications tried to implement their own window packages, chaos 
would result. Facilities are also included in ViewPoint to provide a consistent user 
interface, such as form windows and property sheets. A final reason for including facilities 
is to provide packages that are useful to many clients, such as the simple text facilities. As 
ViewPoint evolves, more facilities useful to a variety of clients will be added. 



The ViewPoint interfaces fall into the following general categories: 



Application registration: 
Windows and display: 
Forms and property sheets: 
User input and keyboards: 

Strings and messages: 

Selection: 
Containers: 

Text display and editing: 
Background management: 



Containee 

Context, Display, StarWindowShell, Window 

FormWindow, FormWindowMessageParse, PropertySheet 

BlackKeys, KeyboardKey, KeyboardWindow, LevellVKeys, 
SoftKeys. TIP, TIPStar 

XChar, XCharSets, XCharSetNNN, XComSoftMessage, 
XFormat, XLReat, XMessage, XString. XTime, XToken 

Selection 

ContainerCache, ContainerSource, ContainerWindow, 
FileContainerShell, FiieContainerSource 

SimpleTextDispiay, SimpieTextEdit, SimpieTextFont 

BackgroundProcess 



Miscellaneous user interface: Attention, Cursor, MenuData, MessageWindow, 

PopupMenu, StarOesktop, Undo 



Miscellaneous: 



Atom, AtomicProf ile. Event, idleControl 



2.2 History 



ViewPoint is the result of past experience with Star and the Xerox Development 
Environment. In late 1982, the Star Performance and Architecture Project concluded that 
Star's monolithic system structure, in which every piece knew about every other piece, 
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hindered its performance. The monolithic structure also made it difficult to develop new 
applications. In addition, there were hundreds of interfaces in the system but no 
distinction between public and private interfaces, which made it difficult for programmers 
to learn how to write applications in the system. 

In contrast to Star, the Xerox Development Environment had a modular system structure 
with a small number of well-documented public interfaces It also encouraged an 
open-ended collection of applications. While it performed well and was open, the Xerox 
Development Environment did not have as consistent a user interface as Star, nor did it 
support Star's multilingual requirements. 

As a result of this study, ViewPoint was created. It has the system structure, documented 
public interfaces, and openness of the Xerox Development Environment, yet supports 
Star's user interface and multilingual requirements. 

While it was initially focused on providing a new foundation for Star, ViewPoint has 
become the basis for more software products from the Office Systems Division. It will 
evolve to replace the current foundation of the Xerox Development Environment and will 
likely support products from organizations outside the Office Systems Division. 

2.3 Philosophy and Conventions 

Viewpoint's philosophy and conventions apply both to applications that interact with the 
user and to packages that implement a facility. Some are just good system-building 
concepts. ViewPoint assumes that programs that run within it are friendly and that they 
are not trying to circumvent or sabotage the system. The system does not try to enforce 
many of these conventions but assumes that clients will adhere to them voluntarily. If 
these conventions are not followed, the system may degrade or break down altogether. 

2.3.1 Supported Public Interfaces 

Systems should be designed to export public interfaces that are well documented and 
relatively stable. By defining a set of primitive facilities and stressing their stability, 
applications are encouraged to depend on the existing ViewPoint facilities rather than on 
other applications packages. This promotes an open architecture in which applications can 
be developed and loaded with relative ease, exchanging information among themselves 
while maintaining the independence of client modules. The open architecture allows 
designing for unknown applications as well as the class of applications expected in Star. 

In keeping with an open architecture, ViewPoint does not make far-reaching assumptions 
about the applications that run above it. While ViewPoint provides facilities that make 
certain styles of applications easy, it does not preclude other styles of applications. 

2.3.2 Plug-ins 

ViewPoint is self-contained in that it does not import procedures that it expects a client to 
supply. Rather it waits, in effect, for clients to call it and state that they want to 
implement some facility. This is referred to as a plug-in approach: an application plugs 
itself in to a lower layer of software. 
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Plug-ins encourage modularity at the client level. Because ViewPoint can be run by itself 
(although it does not do much), it can also be run with just one application plugged in. 
Thus each application can be implemented and debugged individually, which simplifies 
system development. 

Plug-ins also can break a dependency that would create a comple.K dependency graph. For 
example, the desktop has a dependency on the applications that appear in the desktop, [f 
the desktop depended directly on the applications, it would have to change every time a 
new application was created. By having the applications plug themselves into the desktop, 
the direct dependency is broken. 

2.3.3 Don't Preempt the User 

Clients should avoid dictating what the user must do. The user should be free to interact 
with different applications as desired. For example, the current selection is something- 
that the user should control. It should be changed only as a result of user actions. A 
background process should not change the selection out from under the user. 

2.3.4 Don't Call Us. We'll Call You 

Because the user is in control, a program must wait for the user to interact with it. The 
method of interacting with the user that is prevalent in terminal-oriented user interfaces 
is to get a command from the user and execute it, which results in the client regaining 
control while it awaits user input. With potentially multiple applications active 
simultaneously, the user should be free to interact with the one of his choosing. 
Viewpoint's input facilities notify a window when the user inputs to that window. 

Events are another case in which the system calls the client. For example, a client may 
need to do something when the user logs in. If the client registers a procedure with the 
appropriate event, the procedure is invoked when the event occurs. 
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This Viewpoint application programmer's guide is intended to point the programmer to 
the most important parts of the most important interfaces needed for writing an 
application in ViewPoint. 

ViewPoint is a collection of interfaces to be used for writing application programs. It is 
primarily intended to support applications like those in the ViewPoint workstation; that 
is, there is support for icons, windows, property sheets, and so forth. 

The first section (3.1 Guide) contains a jump table of the form, "If your application does X, 
then you use interfaces A and B; also, you need to understand C and D, and you probably 
want to read section 3.1.x." The subsections (3.1.x) provide more detail about A, B, C, and 
D, pointing the programmer to the most important types and procedures in an interface. 
The second section (3.2 Getting Started) contains essential information for first-time 
ViewPoint programmers. Section 3,3 provides some flow of control descriptions for several 
common scenarios. It describes which interfaces call which client procedures when, and so 
forth. Section 3.4 discuss some programming conventions specific to ViewPoint interfaces. 
Section 3.5 contains a summary of all the ViewPoint interfaces. 

First, we briefly define an application from the user's point of view: The user sees the icons 
on the desktop and can operate on them in various ways. You can select an icon with the 
mouse and open it to display its contents. Or by selecting the icon and pressing PROPS, you 
can examine and change the icon's properties through a window called a property sheet. 
After an icon is opened, he can examine the properties of the contents and change them by 
again using the property sheet. By selecting one icon, pressing COPY or MOVE, and then 
selecting another icon, he can perform various application-specific operations. This is 
often referred to as "dropping one icon onto another." Each application attaches a different 
meaning to the drop-on operation. For example, the folder takes the icon dropped onto it 
and adds it to the folder. The printing application (printer icon) prints the icon dropped 
onto it. 

From the application's point of view, an icon is just a picture that represents a file. Files 
have a file type, and an application operates on all files of the same type. Thus when the 
user selects a folder icon, he or she is actually selecting a file with file type of folder. When 
the user performs some operation on an icon, the desktop calls the appropriate application 
based on the file type of the file the selected icon represents. 
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3.1 Guide 

The following table can help you readily find a desired section. 

3.1.1 Guide to the Guide 

If your application ... See section 

... Appears as an icon: 

- Read about icon applications in 3.2 Getting Started 3.2.2 

- Use Containee to register the icon's behavior 3. 1 .2 

... Opens a window: 

- Use StarWindowShell to create a window 3.1.3 

- Use MenuOata to construct menus 3. 1.4 

... Manages the contents of a window: 

- Use Display and Window to display information 3. 1.5 

- Supply a TIP. Notify Proc to process user actions 3. 1.5 

- Use Selection to share data between applications 3. 1.5 

- Use Context to save data with the window 3. 1.5 

... Puts up a Property Sheet: 

- Use Property Sheet and Form Window interfaces 3. 1.6 
... Manipulates strings: 

- Use the XString interfaces (including XFormat, XToken, XChar) 3. 1.7 
... Displays messages to the user: 

- Use the XMessage and Attention interfaces 3. 1 .8 
... Displays a list of items like a folder: 

- Use the Container interfaces (ContainerWindow, ContainerSource) 3. 1.9 
... Redefines the function keys: 

- Use the SoftKeys interface 3. 1. 10 
... Redefines the Black Keys: 

- Use BlackKeys and KeyBoardKey interfaces 3. 1. 1 1 
... Performs operations in a background process: 

- Use the BackgroundProcess interface 3.1.12 
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3.1.2 Containee 

Containee is an application registration facility. An application is a software package that 
implements the manipulation of one type of file. Containee is a facility for associating an 
application with a file type. (§3.2.2 explains how an application registers itself and is then 
invoked to perform various operations). The most important items in Containee are: 



implementation 

Setlmpiementation 

GenericProc 

PictureProc 
Data, DataHandle 



A record containing several client procedures. 
Registers an application. 

Client procedure called to perform OPEN, PROPS, COPY/MOVE- 
onto, and so forth. 

Client procedure called to display an icon picture. 
Uniquely identifies a file. 



3.1.3 Application Windows 



StarWindowShell allows a client to create a Star-like window. A StarWindowShell 
window has a header that contains a title, commands, and pop-up menus. The window 
may have scroll bars, both horizontal and vertical. It also has interior window space that 
may contain anything the client desires. StarWindowShell also supports the notion of 
"t^^ opening within. 

A StarWindowShell is a window (see Window interface) that is a child of the desktop 
window. A StarWindowShell has an interior window that is a child of the 
StarWindowShell and is exactly the size of the available window space in the shell, that is, 
the window shell minus its borders and header and scrollbars. The interior window may 
have child windows created by the client. These children of the interior window are called 
body windows. The client may create an arbitrary number of body windows and may 
arrange them arbitrarily. Note: Because the body windows are children of the interior 
window, they are clipped by the interior window. 



The client may manage body windows directly, including all display and notification (user 
input). Body windows can also be managed by various interfaces provided by ViewPoint, 
such as FormWindow and ContainerWindow. These interfaces have Create procedures 
that take a body window and turn it into a particular kind of window, providing all the 
display and notification handling for the window. 



The most important items in StarWindowShell are: 

Create Creates a StarWindowShell window. 

CreateBody Creates a body window. 

ShellFromChild Returns the window shell, given a body window. 

SetRegularCommands Places commands in the header of a StarWindowShell. 
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AddPopupMenu Adds a pop-up menu to the header of a StarWi ndowShel I . 

3.1.4 Menus 

A menu is a list of named commands. When the user selects a menu command, a client 
procedure is called. The MenuData interface allows menu items and menus to be created. 
MenuData does not address the user interface for menus. Menu items may appear as 
commands in the header of a star window shell (StarWindowShell.SetRegularCommands). 
Entire menus may be accessed via a pop-up symbol in the header of a window shell 
(StarWindowShell.AddPopupMenu) Menu items may be added to the pop-up menu that is 
available to the user through the attention window (Attention.AddMenultem). 

The most important items in MenuData are: 

Createitem Creates a menu item. 

MenuProc A client procedure that is called when the user selects a 

menu item. 

CreateMenu Creates a menu from an array of menu items. 

3.1.5 Managing a Body Window 

Clients can manage their own body windows. This involves handling both display and 
notification (user input), and often includes managing the current selection. Display is 
done by providing a window display procedure. Notifications are received through a client- 
provided TiP.NotifyProc. The Selection interface manages the current selection. Arbitrary 
data associated with a window can be saved with the window by using the Context 
interface. 



3.1.5.1 Display 

The Window interface calls the client's display procedure to repaint the contents of the 
window. It is called when the window is initially made visible. It is also called when the 
window suddenly becomes more visible because an overlapping window was moved, or 
when the window is scrolled so that the part of it that was invisible before becomes visible. 
The display procedure should use the Display and/or SimpleTextDisplay interfaces to 
display bits in the window. The display procedure can be set when a window shell's body 
window is created (starWindowShell.CreateBody) or by calling windoyv.SetDisplayProc. 



The most important item in Window is the client's display procedure. There is no type for 
this procedure, but it is discussed in the Window interface chapter. Other important 
items: 

Box Defines a rectangle in a window. 

Place Defines a point in a window. 
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The most important items in Display are: 



Black 



Displays a black box. 



White 



Displays a white box. 



Invert 



Inverts the bits in a box. 



Bitmap 



Displays an arbitrary array of bits. 



The most important item in SimpleTextDispiay is: 



StringlntoWindow 



Displays a string in a window. 



3.1.5.2 TIPandTIPStar 



TIP provides basic user input facilities through a flexible mechanism that translates 
hardware-level actions from the keyboard and mouse into higher-level client action 
requests (result lists). The acronym TIP stands for terminal interface package. This 
interface also provides the client with routines that manage the input focus, the periodic 
notifier, and the STOP key. 

The basic notification mechanism directs user input to one of many windows in the 
window tree. Each window has a TiP.Table and a TiP.NotifyProc. The table is a structure 
that translates a sequence of user actions into a sequence of results that are then passed to 
the notify procedure of the window. 

The Notifier process dequeues user events, determines which window the event is for, and 
tries to match the events in the window's Table. If it finds a match in the table, it calls the 
window's NotifyProc with the results specified in the table. If no match is found, it tries 
the next table in the window's chain of tables. If no match is found in any table, the event 
is discarded. 

TIP tables provide a flexible method for translating user actions into higher-level client- 
defined actions. They are essentially large select statements with user actions on the left 
side and a corresponding set of results on the right side. Results may include mouse 
coordinates, atoms, and strings for keyboard character input. 

ViewPoint provides a list of normal tables that contain one production for each single user 
action. Client programmers can write their own table to handle special user actions and 
link it to system-defined tables, letting those tables handle the normal user actions. These 
system-defined tables are accessible through the TIPStar interface and are described in 
Appendix A. 

input Focus. The input focus is a distinguished window that is the destination of most user 
actions. User actions may be directed either to the window with the cursor or to the input 
focus. Actions such as mouse buttons are typically sent to the window with the cursor. 
Most other actions, such as keystrokes, are sent to the current input focus. Clients may 
make a window be the current input focus and be notified when some other window 
becomes the current input focus. 
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The current selection and the current input focus often go together. If the window in which 
a selection is made also expects to receive user keystrokes (function keys as well as black 
keys), TiP.SetlnputFocus should be called at the same time as Selection.Set is called. This is 
also the time to call SoftKeys.Push or KeyboardKey.RegisterClientKeyboards, if necessary. 

Modes. TIPStar also provides the notion of a global mode to support MOVE, COPY, and same. 
When the user presses down and releases the move, COPY, or same keys, the client that 
currently has the input focus will receive the notification and should call TiPStar.SetMode 
This changes the mouse TIP table so that atoms specific to the mode are produced rathfr- 
than normal atoms when the user performs mouse actions. For example, in copy mode 
"Copy Mode Down" instead of "PointDown" is produced when the user presses the left 
mouse button. This informs the client that receives the atom that it should attempt to copy 
the current selection rather than simply select something. 

The most important items in TIP are: 

NotifyProc Client procedure that is called to handle a user action. 

Results, ResultObject Right side of the table entry that matched the user action. 
SetlnputFocus Sets a window to be the current input focus. 

The most important items in TIPStar are: 

NormalTable Returns the chain of system-provided TIP tables. 

SetMode Sets the entire environment into MOVE, COPY, or SAME As 

mode, thus changing the results produced for mouse clicks. 

3.1.5.3 Context 

The Context interface allows arbitrary client data to be associated with a window. Client 
data is usually allocated and associated with the window when the window is created. The 
data may be retrieved any time, such as at the beginning of the client's display procedure 
and TIP. NotifyProc. 

The most important items in Context are: 

Create Associates data with a window. 

Find Recovers the data previously associated with a window. 



3.1.5.4 Selection 

The Selection interface defines the abstraction that is the user's current selection. It 
provides a procedural interface to the abstraction that allows it to be set, saved, cleared, 
and so forth. It also provides procedures that enable someone other than the originator of 
the selection to request information relating to the selection and to negotiate for a copy of 
the selection in a particular format. 
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The Selection interface is used by two different classes of clients. Most clients wish merely 
to obtain the value of the current selection in some particular format; such clients are 
called requestors. These programs call Convert (or maybe ConvertNumber, which in turn 
calls Convert), or Query, or Enumerate. These clients need not be concerned with many of 
the details of the Selection interface. 

The other class of clients are those that own or set the current selection; these clients arc 
called managers. A manager calls Selection.Set and provides procedures that may be called 
to convert the selection or to perform various actions on it. The manager remains in 
control of the current selection until some other program calls Selection.Set. These clients 
need to understand most of the details of the Selection interface 

A client that is managing its own body window will be both a selection requestor and a 
selection manager in different parts of the code. For example, when the user selects 
something in another window and copies it to the client's window, the client must call 
Selection. Con vert to request the value of the selection in a form appropriate to the 
application. On the other hand, when the user clicks a mouse button in the client's 
window, the client usually becomes the selection manager by calling Selection.Set. 

The most important items in Selection are: 

Convert Request the value of the selection in some target form. 

Value A record containing a pointer to the converted selection 

value, among other things. 

CanYouConvert Returns true if the selection manager can convert the 

selection to a particular target type. 

Set Called by a selection manager to become the current 

manager. 

ConvertProc Manager-supplied procedure that will be called to convert 

the selection to some target type. 

ActOnProc Manager-supplied procedure that will be called to perform 

some action on the selection, such as mark, unmark, clear. 

3.1.6 Property Sheets and Form Window 

A property sheet shows the user the properties of an object and allows the user to change 
these properties. There are several different types of properties, the most common ones 
being boolean, choice (enumerated), and text. 
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From a client's point of view, a property sheet is simply a StarWindowShell with a 
FormWindow as a body window. A property sheet is created by calling PropertySheet. Create, 
providing a procedure that will make the form items in the FormWindow (a 
FormWindow.MakeltemsProc), a list of commands to put in the header of the property sheet, 
such as Done, Cancel, and Apply (PropertySheet.Menuitems), and a procedure to call when 
the user selects one of these commands (a PropertySheet.MenuitemProc). When the user 
selects one of the commands in the header of the property sheet, the client's 
PropertySheet.MenuitemProc is called. If the user selected Done, for example, the client can 
then verify and apply any changes the user made to the object's properties 

The most important items in PropertySheet are: 

Create Creates a property sheet. 

Menuitems Used for specifying which commands to put in the header of 

the property sheet. 

MenultemProc Client procedure called when the user selects one of the 

commands in the header. 

The most important items in FormWindow are: 

MakeitemsProc Client procedure called to create the items in the form 

MakeXXXItem Makes a form item. XXX can be Boolean, Choice, Text, 

Integer, Decimal, Window, TagOnly, Command. 

GetXXXItemValue Returns the current value of an item. XXX can be Boolean, 

Choice, Text, Integer, Decimal, Window, TagOnly, 
Command. 



3.1.7 XString, et al. 



The Xerox Character Code Standard defines a large number of characters, encompassing 
not only familiar ASCII characters but also Japanese and Chinese Kanji characters and 
others to provide a comprehensive character set able to handle international information 
processing requirements. liecause of the large number of characters, the data structures 
in XString are more complicated than a LONG string's simple array of ASCII characters, but 
the operations provided are more comprehensive. 

Characters are 16-bit quantities that are composed of two 8-bit quantities, their character 
set and character code within a character set. The Character Standard defines how 
characters may be encoded, either as runs of 8-bit character codes of the character set or as 
16-bit characters where the character set and character code are in consecutive bytes. (See 
the XChar chapter for information and operations on characters.) 

Viewpoint provides a string package consisting of several interfaces that support the 
Xerox Character Code Standard. XString provides the basic data structures for 
representing encoded sequences of characters and some operations on these data 
structures. XFormat converts other types into XStrlngs. XToken parses XStrings into other 
TYPES. XChar defines the basic character type and some operations on it. XCharSets 
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enumerates the character sets defined in the Standard. A collection of interfaces 
'''^mi^ enumerate the character codes of several common character sets (XCharSetNNN). XTime 

provides procedures to acquire and edit times into XStrings and XStrings into times. 

3.1.8 XMessage and Attention 

XMessage supports translation into other languages of text displayed to the user. It does 
not include any string constants in the code of an application. Rather, all the string 
constants for an application are declared in a separate module and registered with 
XMessage. Then whenever the application needs a string constant, it obtains it by calling 
XMessage.Get. Several commonly used messages such as "Yes", "No", and days of the 
week are detined in XComSoftMessage. 

The most important items in XMessage are: 

Get Retrieves a message. 

RegisterMessages Registers all the messages for an application. 

The Attention interface provides a global mechanism for displaying messages to the user. 
Attention provides procedures to post messages to the user in the attention window, clear 
the attention window, post a message and wait for confirmation, and so forth. 

^ ^.y The most important items in Attention are: 

Post Posts a message in the attention window. 

Clear . Clears the attention window. 

formatHandle XFormat. Handle that may be used to format strings into the 

attention window. 

3.1.9 Containers 

The Container interfaces (ContainerSource, ContainerWindow, FileContainerSource, 
FileContainerShell, and ContainerCache) provide the services needed to implement an 
application that appears as an ordered list of items to be manipulated by the user. Star 
Folders are a typical example of such an application. 

Figure 3-1 shows the relationships among the various interfaces and potential clients. 
Each interface is described below, followed by a discussion of which interfaces an 
application might need to use. 
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Figure 3.1 Container Interface Dependencies 

The ContalnerWindow interface takes a window and a ContainerSource and makes the 
window behave like a container. It maintains the display and manages scrolling, 
selection, and notifications. Note: This interface does not depend on NSFiie. 

A container source is a record of procedures that implement the behavior of the items in a 
container and the behavior of the container itself. ContainerWindow obtains the strings of 
each item by calling one of these procedures. ContainerWindow also performs user 
operations on items (such as open, props, delete, insert, take the current selection, and 
selection conversion) by calling other procedures in the record. A container source can be 
thought of as a supply (source) of items for a container window. The ContainerSource 
interface defines each of the procedure types that a container source must implement. 
ContainerSource contains types only. 



ContainerCache provides the implementor of a container source with an easy-to-use cache 
for storing and retrieving the strings of each item and some client-specific data about each 
item. 

FileContainerSource provides an NSFIIe-backed container source. It takes an 
NSFile.Reference for a file that has children, and each child file becomes an item of the 
container. Facilities are provided to .specify the columns based on NSFiie attributes. 

The FileContainerShell interface takes an NSFiie and column information (such as 
headings, widths, formatting) and creates a FileContainerSource, a StarWindowShell, and 
a container window body window. Most NSFile-backed container applications can use this 
interface, which greatly simplifes the writing of those applications. 
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Each of the items in a container must behave like to a file on the desktop; that is, each 
item must be able to be opened, show a property sheet, take a selection, and so forth. 
However, the items need not be backed by files. If the container is backed by an NSFile that 
has children, then the FileContainerShell interface is the only interface the client needs to 
use. Otherwise, the client must implement a container source and make most of the calls 
that the FileContainerSheil implementation makes; that is, starWindowShell. Create, 
StarWindowShell.CreateBody, ContainerWindow.Create. 

3.1.10 SoftKeys 

The SoftKeys interface provides for client-defined function keys designated to be the 
isolated row of function keys at the top of the physical keyboard. It also provides a 
SoftKeys window whose "keytops" may be selected with the mouse to simulate pressing 
the physical key on the keyboard. Such a window is displayed on the user's desktop 
whenever an interpretation other than the default SoftKeys interpretation is in effect. 
(The default is assumed to be the functions inscribed on the physical keys.) 

The most important items in SoftKeys are: 

Labels, LabelRecord Strings to display on the keytops in the SoftKeys window. 
Push Install a client-specific interpretation for the soft keys. 

Rennove Remove a previously installed interpretation. 

3.1.11 Client-Deftned Keyboards 

KeyboardKey is a keyboard (the central set of black keys on the physical keyboard) 
registration facility. It provides clients with a means of registering system-wide 
keyboards (available all the time, like English, French, European), a special keyboard 
(like Equations), and/or client-specific keyboards (those that are available only when the 
client has the input focus). The labels from these registered keyboards are displayed in the 
softkeys window when the user holds the KEYBOARD key down. 

The BlackKeys interface provides the data structures that define a client keyboard. 

The most important items in KeyboardKey are: 

AddToSystemKeyboards Adds a keyboard to the system keyboards. 
RegisterClientKeyboards Establishes the keyboards available to the user. 

The most important items in BlackKeys are: 

Keyboard, KeyboardObject A keyboard interpretation. 
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3.1.12 Background Process 



The BackgroundProcess interface provides basic user feedback and control facilities to 
clients that want to run in a process other than the the Notifier process (see the Notifier 
section below). Once registered with BackgroundProcess, the client process can use 
Attention to post messages and check to see if the process has been aborted by the user. 
The user can look at the messages posted by the process and abort the process. The 
primary procedure in BackgroundProcess is ManageMe, which is typically the first 
procedure called from a background process. 



3.2 Getting Started 



This section is a guide for programmers who have never used the ViewPoint interfaces. It 
shows how two common types of applications are written using ViewPoint. 

A user can invoke a program in the ViewPoint environment in two ways. First is to select 
an icon and press a function key such as OPEN, PROPS, COPY, or MOVE. This type of program 
is called an icon application. Second, the user may simply select an item in the attention 
window's pop-up menu. For example, in OS 5, a Show Size command reports on the size of 
the selected icon's file. The following sections describe how to write each of these types of 
programs. 



3.2.1 Simplest Application 



The simplest way to get a program running in the ViewPoint environment is to have the 
program add an item to the attention window's pop-up menu. When the user selects that 
item, the program is called. See the SampleBWSTool for an example of this type of 
application. Excerpts from SampleBWSTool: 

Init: PROCEDURE a { 

sampleTool: xstring.ReaderBody «-xstrjng.FromSTRING["Sample Toor'L]; 
Attention.AddMenultem [ 
MenuOata.Createltem [ 

zone: sysZ, 

name: ©sampleTool, 

proc: MenuProc] ]; 

}; 

— Mainline code 
init[I; 



When the application is started, its startup (mainline) code creates a MenuOata.ltemHandle 
by calling MenuOata.Createltem and then adds this item to the attention window's menu by 
calling Attention.AddMenultem. Now the MenuProc passed to MenuOata.Createltem is 

called when the user selects the Sample Tool item in the attention window's pop-up menu. 
The MenuProc can then do whatever is appropriate for the application. 
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3.2.2 Icon Application 

Getting an icon application running in ViewPoint is a little more complex. The basic idea 
is that an application operates on files of a particular type. When an application is started, 
it registers its interest in files of that type. Whenever the user operates on a file of that 
type, the application gets called. Here is a skeletal example of some application code; the 
full explanation follows: 

— Constants and global data 

samplelconFileType: NSFile.Type a . . .; 

oidlmpi, newlmpi: Containee.implementation <— []; 

-- Containee.implementation procedures 

GenericProc: Containee.GenericProc ■ { 

SELECT atom FROM 

canYouTakeSeiection > > . . . 
takeSelection a > . . . 
takeSeiectionCopy a > . . . 
open • > . . . 
props ■ > . . . 

ENDCASE « > . . . 

PictureProc: Containee.PictureProc a { 
Display.Bitmap [. . .]; 

h 

— Initialization procedures 

InitAtoms: procedure * { 

open <-Atom.MakeAtom["Open"L]; 
props <- Atom . Ma keAtom [ " Props " L] ; 

canYouTakeSeiection <-Atoni.MakeAtom["CanYouTakeSelection"L]; 
takeSelection <-Atom.MakeAtom["TakeSeiection"L]; 
takeSeiectionCopy Atom. MakeAtom["TakeSelectionCopy"L]; 

}; 

FindOrCreatePrototypelconFiie: procedure * {...}; 

Setlmpiementation: procedure » { 
newlmpi. genericProc ir- GenericProc; 
newlmpi. pictureProc PictureProc; 

oldlmpi «-containee.Setlmplementation [samplelconFileType, newlmpi ]; 

}; 

— Mainline code 
InltAtomsll; 

FindOrCreatePrototypelconFileH; 
SetlmplementationH; 
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The most important thing to note in the above example is the Setlmpiementation 
procedure and the call to Containee.Setlmpiementation in particular. This call associates 
the application's implementation (newimpi) with a particular file type 
(samplelconFileType). This implementation is actually a Containee.lmplementation that is 
a record which contains procedures. Whenever the user operates on files of type 
samplelconFileType, the procedures in the Implementation record are called. An 
understanding of how this works requires an understanding of how the ViewPoint desktop 
implementation operates. 

First, some background about NSFiles. All NSFiles have: 

• A name 

• A file type (long cardinal) 

• A set of attributes, such as create date 

• Either: 

• Content, such as a document 

• Children that are also NSFiles, such as a folder. 

An NSFile that has children is often called a directory. Fine point: anNSFile can actually have both 
content and children; however, to simplify this discussion, this point is ignored. Note: Because the 
children of an NSFlie can themselves have children, NSFile supports a hierarchical file 
system. 

A ViewPoint desktop is an NSFile that has children. An on-screen icon picture represents 
each child file of the desktop's NSFile The desktop display of rows of "icons" is an illusion. 
The word icon is in quotes because, from the programmer's point of view, there really is no 
such thing as an icon. The only things that really exist are files (NSFiles), icon pictures, 
and application code. 

Immediately after logging on, the desktop implementation enumerates the child files of 
the desktop file and calls an application's Containee.PictureProc for each child file, based on 
the child file's type. Each application's Containee.PictureProc should then display the icon 
picture for that file. 

After logon is complete and the desktop is displayed, the desktop implementation receives 
user actions such as mouse clicks and presses of the OPE.N or PROPS keys. For example, 
assume the user selects an icon picture and presses OPEN. The desktop implementation 
determines the file type for the file represented by the icon picture the user selected and 
then calls the Containee.GenericProc for the application that operates on files of that type, 
requesting that the application open the icon. It also passes the application a unique 
identifier for the particular file selected. At this point, the application can do whatever is 
appropriate for that application. Typically, the application opens the file, reads some data 
out of it, creates a StarWindowShell, and displays the contents of the file in the window in 
some application-specific form. 

The desktop implementation does not call an application directly. Rather, ViewPoint 
maintains a table of file-type/Containee. Implementation pairs. When an application calls 
Containee.Setlmpiementation, an entry is added to the table. When the desktop 
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implementation calls an application, it obtains the Containee. Implementation for the 
application by looking it up in the table (it actually calls Containee.Getimptementation). 

3.2.3 Operational Notes 

To write an icon application, a programmer must obtain a unique file type. Contact your 
ViewPoint consultant to obtain one. 

In the example above, the application in its initialization code checks to be sure a 
prototype file exists and, if not, creates one. This usually involves creating a file with the 
proper file type for this application. This allows the user to get started with the 
application, usually by copying the blank prototype out of a special folder of prototypes. 

Note: There is a clear distinction between a prototype file for an application and a bed file 
that contains the code for the application. All bed files are of the same type, while each 
prototype file is different for each application. 

3.3 Flow Descriptions 

The following flow descriptions are intended to show how everything is related. For each 
example scenario, the exact sequence of calls is described, including ViewPoint interfaces 
and clients. 

3.3.1 Select an Icon 

The user points at an icon on the desktop 

• When the mouse button goes, down over an icon picture, the notification goes to the 
desktop implementation's TiP.NotifyProc The NotifyProc will be passed a window. Place 
and a "PointDown" atom. The desktop implementation determines what file is 

represented by that icon picture. Fine point: The desktop implementation mamtain.s a tnapping 
from icon picture locations to NSFile.References. 

• The desktop implementation calls Containee. Getlmplementation, passing in the file 
type of the file and getting back the Containee.! mplementation for that file type. 

• The desktop implementation calls the Containee. PictureProc that is in the 
Implementation; (that is, impl.pictureProc), passing in: 

• data: the NSFile.Reference for the file 

• old: normal 

• new: highlighted 

• The application's PictureProc displays a highlighted version of its icon picture, 
perhaps simply calling Olsplay.ln vert. 

• When the mouse button goes up (a "PointUp" atom), the desktop implementation 
becomes the current selection manager by calling Selection. Set. It sets the desktop 
window to be the current input focus by calling TiP.SetlnputFocus. Setting the input 
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focus to be the desktop window ensures that keys such as OPEN, props, COPY.and so 
forth, will all go to the desktop's Notif yProc. 



• END. 



3.3.2 PROPS of an Icon 



Assume an icon on the desktop is selected. The user presses PROPS. After changing some 
items in the property sheet, the user selects Done. 

• The desktop implementation's TiP.NotifyProc gets the notiiication (a "PropsDown" 
atom) and determines which icon picture is currently selected and what file is 
represented by that icon picture. 

• The desktop implementation calls Containee.Getlmpiementation, passing in the file 
type of the file and getting back the Containee.lmpiementation for that file type. 

• The desktop implementation calls the Containee.GenericProc that is in the 
Implementation; (that is, impi.genericProc), passing in: 

• data: the NSFiie. Reference for the file 

• atom: "Props" 

• changeProc: a Containee.ChangeProc that belongs to the desktop implementation 

• changeProcData: a pointer to some desktop implementation data that identifies 
the icon/file being operated on. 



• The application's GenericProc creates a property sheet by calling PropertySheet.Create. 

It probably also opens and retrieves some data out of the file (using various NSFiie 
operations) and uses that data to set the initial values of the items in the property 
sheet. 

• Typically, the client wants to save the NSFiie. Handle for the file while the property 
sheet is open. In addition, if the opening and closing of the property sheet might cause 
the file's attributes to change, the application's GenericProc must save the passed 
changeProc and changeProcData. A typical example is when the file's name is one of 
the items in the property sheet and the user can change the name. The data is saved 
by allocating a record with this data in it and passing a pointer to the record as the 
clientData parameter to PropertySheet.Create. Later, when the user selects Done or 
Apply, this data may be recovered (see the rest of this fiow description). Note: This 
data cannot be saved in a local frame (such as that of the GenericProc) because the 
GenericProc must return to the notifier after creating the property sheet: when the 
user selects Done or Apply that is a new call stack. The client data should not be saved 
in a global frame because more than one property sheet may be open for a particular 
application. 

• The application's GenericProc returns the StarWindowSheli. Handle for the property 
sheet. 

• The desktop implementation displays the property sheet by calling 
StarWindowShell.Push; then the desktop's NotifyProc returns to the Notifier. 
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• The user changes some items and then selects Done. 

• The PropertySheet implementation calls the client's PropertySheet.MenultemProc that 
was passed in to PropertySheet.Create, passing in: 

• shell : the StarWindowShell for the property sheet 

• formWindow: the Form Window for the property sheet 

• menultem: done 

• clientData: the pointer to the client's data that was passed to PropertySheet.Create 

• The client's MenultemProc recovers the client's data (the file handle, the changeProc 
and changeProcData, and any other relevant client data) from the clientData 
parameter. It determines if the user made any changes and, if so, updates the file 
accordingly and calls the changeProc, passing in the changeProcData, the file 
reference, and a list of the changed file attributes. 

• The desktop's ChangeProc causes the icon picture to be redisplayed, because changing 
an attribute such as the name requires the picture to be updated with the new name. 

• The client's MenultemProc returns to the PropertySheet implementation, indicating 
that the property sheet should be destroyed. 

• The PropertySheet implementation destroys the property sheet by calling 
StarWindowShell.Pop and returns to the Notifier 

• END. 

3.3.3 OPEN an Icon 

Opening an icon is similar to opening a property sheet for an icon. 

3.3.4 COPY Something to an Icon 

Assume something has been selected. The user presses COPY and then points at an icon. 

• When the user presses COPY, the NotlfyProc for the window that currently has the 
input focus (and the selection) is called. It calls TiPStar.SetMode [copy] to set the 
environment into copy mode and then returns to the Notifier. It might also call 
Cursor.Set to change the cursor shape to indicate move mode. 

• SetMode replaces the NormalMouse.TIP table with the CopyModeMouse.TIP table. 

• The user presses the mouse button down over an icon on the desktop. 

• The desktop's NotifyProc gets called with a "CopyModeDown" atom (instead of a 
"PointDown" atom because of the TIP table switch). It determines what file is 
represented by the icon picture the user is pointing at. It calls 
Containee.Getlmplementation, passing in the file's type and getting back a 
Containee. Implementation It calls the Implementation's GenericProc passing in: 

• data: the NSFile.Reference for the file 
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• atom: "CanYouTake" 

• The application's GenericProc calls Selection.CanYouConvert or Seiection.HowHard to 

determine if the current selection can be converted to target type(s) that the 
application can take. For example, if the icon being copied to is a printer icon, it calls 
HowHard with targets of interpressMaster and file. 

• The Selection implementation calls the current selection manager's 
Seiection.ConvertProc. It returns an indication of how hard It would be to convert the 
selection to the given target types. 

• The application's GenericProc returns a pointer to true if it determines that it can take 
the current selection and false if it cannot. 

• The desktop implementation changes the cursor shape to a question mark if the 
application's GenericProc returns false. Otherwise, it leaves the cursor as it was. 

• The user releases the mouse button. 

• The desktop's NotifyProc gets called with a "CopyModeUp" atom. It determines what 
file is represented by the icon picture the user is pointing at. It calls 
Containee.Getlmplementation, passing in the file's type and getting back a 
Contained mplementation. It then calls the Implementation's GenericProc, passing in: 

• data: the NSFile. Reference for the file jg/n^ 

• atom: "TakeSelectionCopy" 

• changeProc: a Containee.ChangeProc that belongs to the desktop implementation 

• changeProcData: a pointer to some desktop implementation data that identifies 
the icon/file being copied to 

• The application's GenericProc calls Selection.Convert or (Selection. Enumerate) to convert 
the selection to the desired type. The application then operates on the converted 
selection value as appropriate for that application. For example, the printer icon 
application converts the selection to an interpressMaster and sends the master to the 
printer. (See the Selection chapter for a full flow description of the selection 
mechanism.) 

• The application's GenericProc returns to the desktop's NotifyProc, which returns to 
the Notifier. 

• END. 

3.4 Programming Conventions 

The ViewPoint environment assumes that the programs that run in it are friendly and 
that they are not trying to circumvent or sabotage the system. The system does not enforce 
many of the conventions described here but assumes that application programmers will 
adhere to them voluntarily. If these conventions are not followed, the ViewPoint 
environment may degrade or break down altogether. 
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The most important principle is that users should have complete control over their 
environment. In particular, clients shall not pre-empt users. A user should never be forced 
by a client into a situation where the only thing that can be done is to interact with only 
one application. Furthermore, the client should avoid falling into a particular mode when 
interacting with the user; that is, an application should avoid imposing unnecessary 
restrictions on the sequence of user actions. 

This goal of user control has implications for the designs of applications. A client should 
never seize control of the processor while getting user input. This tends to happen when 
the client wants to use the "get a command from the user and execute it" mode of 
operation. Instead, an application should arrange for ViewPoint to notify it when the user 
wishes to communicate some event to the application. This is known as the "Don't call us, 
we'll call you" principle. 

The user owns the window layout on the screen. Although the client can rearrange the 
windows, this is discouraged. Users have particular and differing tastes in the way they 
wish to lay out windows on the display; it is not the client's role to override the user's 
decisions. In particular, clients should avoid making windows jump up and down to try to 
capture the user's attention. If the user has put a window off to the side, then he does not 
want to be bothered by it. 

3.4.1 Notifier 

ViewPoint sends most user input actions to the window that has set itself to be the focus 
for user input; the rest of the actions are directed to the window containing the cursor. (See 
the TIP interface for details on how the decision is made where to send these actions.) A 
process in ViewPoint notes all user input actions and determines which window should 
receive each one. A client is concerned only with the actions that are directed to its 
window; it need not concern itself with determining which actions are intended for it. 

The basic notification mechanism directs user input to one of many windows in the 
window tree. Each window has a TIP'.Table and a TIP. Notify Proc. The table is a structure 
that translates a sequence of user actions into a sequence of results that are then passed to 
the notify procedure of the window. 

There are two processes that share the notification responsibilities, the Stimulus process 
and the Notifier process. The Stimulus process is a high-priority process that wakes up 
approximately 50 times a second. When it runs, it makes the cursor follow the mouse and 
watches for keyboard keys going up or down, mouse motion, and mouse buttons going up 
or down, enqueuing these events for the Notifier process. 

The Notifier process dequeues these events, determines which window the event is for, 
and tries to match the events in the window's table. If it finds a match in the table, it calls 
the window's notify procedure with the results specified in the table. If no match is found, 
it tries the next table in the window's chain of tables. If no match is found in any table, the 
event is discarded. 

The Notifier process is important. To avoid multi-process interference, some operations in 
the system can happen only in the Notifier process. Setting the selection is one such 
operation. The Notifier process is also the one most closely tied to the user. The Notifier 
waits until a NotifyProc finishes for one user action before processing the next user action. 
If an operation takes an extended time to complete (more than three to five seconds), it 
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should be forked from the Notifier process to run in a separate process so that the Notifier 
process is free to respond to the user's actions. Of course, the application writer must take 
great care when stepping into this world of parallel processing 

3.4.2 Multiple Processes, Multiple Instances 

In Viewpoint, many programs can run simultaneously. The designer of a client-callable 
package should bear in mind that several different asynchronous clients may invoke his 
package, so the package should be monitored. 

The simplest design is to have a single entry procedure that all clients must call. While 
one client is using the package, all other clients block on the monitor lock. Of course, no 
state should be maintained internally between successive calls to the package, because 
there is no guarantee that the same client is calling each time. 

This simple approach has the disadvantage that clients are simply stopped for what may 
be a long time, with no option of taking alternate action. To ease this restriction, the entry 
procedure can check a "busy" bit in the package. If the package is busy, the procedure can 
return this result to the client. The client can then decide whether to give up, try 
something else, or try again. This is less likely to tie up an application for a long period, 
and the user can use the application for other purposes. 

If the package is providing a collection of procedures and cannot provide its services in a 
single procedure, the package and its clients must pass state back and forth in the form of 
an object. The package can uso a .single monitor on its code to protect the object, or it can 
provide a monitor as part of each object. If it does the latter, then several clients can be 
executing safely at the same time. 

Some packages require that a client provide procedures that are called by the package. 
The designer of such a package should have these client-provided procedures take an extra 
parameter, a long pointer to client instance data. When the client provides the package 
with the procedures, it'also provides the instance data to pass to the procedures when they 
are called. The client can then use this instance data to distinguish between several 
different instances of itself that are sharing the same code. 

3.4.3 Resource Management 

Programs in the Xerox Development Environment must explicitly manage resources. For 
example, memory is explicitly allocated and deallocated by programs; there is no garbage 
collector to reclaim unused memory. All programs share the same pool of resources, and 
there is no scheduler watching for programs using more than their share of execution 
time, memory, or any other resource. 

Programs must manage resources carefully. If a program does not return a resource when 
it is done with it, that resource will never become available to any other program and the 
performance of the environment will degrade. The most common resource, and one of the 
more difficult to manage, is memory. 

When interfaces exchange resources, clients must be very careful about who is responsible 
for the resource. The program that is responsible for the deallocation of a resource is the 
owner of that resource. One example of a resource is a file handle. If a program passes a 
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file handle to another program, both programs must agree about who owns that file 
handle. Did the caller transfer ownership by passing the file handle, or is it retaining 
ownership and only letting the called procedure use the file handle? If there is 
disagreement between the two programs, either the file will be released twice, or it will 
never be released at all. All interfaces involving resources must state explicitly whether 
ownership is transferred. To ease the problem of memory management when the 
ownership of memory can change, a heap called the system heap is used in ViewPoint. If a 
piece of memory can have its ownership transferred, it is either allocated from the system 
heap or a deallocation procedure must be provided for it. 

The most common resource appearing in interfaces is an XString (Reader or ReaderBody). 
There must be agreement about which program is responsible for deallocating the string's 
bytes. Typically, a string passed as an input parameter does not carry ownership with it; 
implementors of such procedures should not deallocate or change the string. If it is 
necessary for the implementor to modify the string or use it after the procedure returns, 
the implementor should first copy it. Clients should be particularly careful when a 
procedure returns a string to note whether ownership has come with it. 

3.4.4 Stopping Applications 

The Viewpoint, environment consists of cooperating processes. There are no facilities for 
cleanly terminating an arbitrary collection of processes. It is assumed that application 
writers are good citizens and will design their tools to stop voluntarily when asked to stop. 

An application should stop if the user aborts the application. There are two ways to 
determine if the user has aborted an application. (1) An application's window can have a 
TIP.AttentionProc that is called as soon as the user presses the stop key. (2) Procedures in 
the TIP interface can check whether a user has aborted an application with the STOP key in 
the application's window. An application should check for a user abort at frequent 
intervals and be prepared to stop executing and clean up after itself. Because the 
application controls when it checks, it can check at points in its execution when its state is 
easy to clean up. Packages that can be called from several programs should take a 
procedure parameter that can be called to see whether the user has aborted. 

3.4.5 Multinationality 

ViewPoint is designed to support easy transport of applications to other countries. The 
string package (XString, XChar, XFormat, and so forth) supports the Xerox Character Code 
Standard, which allows for strings in many languages to be intermixed. The XMessage 
interface allows user messages to be translated into other languages because the 
application programmer can put all these messages into a module separate from the rest of 
the application code. The KeyboardKey interface supports the addition of keyboards for 
many languages. 

Application programmers are strongly encouraged to allow their application to be 
multilingual. This means for example, using XString for all string operations and using 
XMessage to manage any text that will be displayed to the user. It also means not making 
any language assumptions about characters received from the user. An application that 
expects typing input from the user should be prepared to receive characters from any 
character set. 
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3.5 Summary of Interfaces 

Atom provides the mechanism for making TIP, Event, and Containee atoms. 
AtomicProfile provides a mechanism for storing and retrieving global values. 
Attention provides a means of displaying messages to the user. 

BackgroundProcess provides basic user feedback and control facilities to clients that want 
to run in a process other than the the Notifier process. 

BlackKeys provides the capability to change the interpretation of the central (black) 
section of the keyboard. 

Containee is an application registration facility. It allows an application to register its 
implementation for files of a particular type. 

ContainerCache provides a simple cacheing mechanism for the implementor of a container 
source. 

ContainerSource defines the procedures that must be implemented to provide a source of 
items for a container window. 

ContainerWindow creates a window that displays an ordered list of items that behave like 

icons on a desktop. jflili, 

Context provides a mechanism for clients to associate data with windows. 

Cursor provides facilities for a client to manipulate the appearance of the cursor that 
represents the mouse position on the screen. 

Display provides facilities to display bits in windows. 

Event provides clients with the ability to be notified of events that take place 
asynchronously on a system-wide basis. 

FileContainerShell creates a StarWindowShell with a ContainerWindow as a body 
window that is backed by a FileContainerSource. 

FileContainerSource creates a container source that is backed by a file that has children. 

FormWindow creates a window with various types of form items in it, such as text, 
boolean, choice (enumerated), command, and window. FormWindow is used to create 
property sheets. 

FormWindowMessageParse provides procedures that parse strings to produce various 
FormWindow types. 

IdleControl provides access to the basic controlling module of ViewPoint. 
KeyboardKey is a client keyboard (the central black keys) registration facility. 
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Key board Window provides a particular implementation for a keyboard window. 
LevellVKeys defines the names of the physical keys. 
MenuOata allows menus and menu items to be created. 

MessageWindow provides a facility for posting messages in a window to the user . 

PopupMenu allows a menu to be displayed (popped up) anywhere on the screen. 

PropertySheet creates a property sheet. A property sheet shows the properties of some 
object to the user and allows the user to change the properties. 

Selection provides the facilities for a client to manipulate the user's current selection. It 
also provides procedures that enable someone other than the originator of the selection to 
request information relating to the selection and to negotiate for a copy of the selection in 
a particular format. 

SimpieTextOisplay provides facilities for displaying, measuring, and resolving strings of 
Xerox Character Code Standard text. It can handle only nonattributed single-font text. 

SimpleTextEdit provides facilities for presenting short, editable pieces of text to the user. 

SimpleTextFont provides access to the default system font that is used to display 
Viewpoint's text, such as the text in menus, the attention window, window names, 
containers, property sheet text items, and so forth. 

SoftKeys provides for client-defined function keys designated to be the isolated row of 
function keys at the top of the physical keyboard. 

StarOesktop provides access to the user's desktop file and window. 

StarWindowShell provides facilities for creating Star-like windows. 

TIP provides basic user input facilities through a flexible mechanism that translates 
hardware level actions from the keyboard and mouse into higher-level client action 
requests. 

TIPStar provides access to Viewpoint's normal set of TIP tables. 

Undo provides facilities that allow an application to register undo opportunities, so that 
when the user requests that something be undone, the application is called to do so. 

Window defines the low-level window management package used by ViewPoint. 

XChar defines the basic character type as defined in the Xerox Character Code Standard as 
well as some operations on it. 

XCharSetNNN enumerates the character codes in character set NNN. 

XCharSets enumerates the character sets defined in the Xerox Character Code Standard. 
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XComSoftMessage defines messages for some commonly used strings, such as Yes, No, 
day-of-the-week, month,and so forth. 

XFormat converts various types into XStrings. 

XLReai supports manipulation of real numbers with greater precision than Mesa reals. 

XMessage supports the multilingual requirements of systems that require the text 
displayed to the user be separable from the code and algorithms that use it. 

XString provides the basic data structures for representing encoded sequences of 
characters as defined in the Xerox Character Code Standard. It also provides several 
operations on these data structures. 

XTime provides facilities to acquire and edit times into XStrings and XStrings into times. 
XToken parses XStrings into other types 
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4.1 Overview 

ApplicationFolder provides access to the folder that contains ail the component tiles of an 
application. A full application is composed of one or more beds, a message file, a 
description file, and other data files, such as .TIP or .Icons. These components are put into 
a folder with a specific file type, called an Application (or ApplicationFolder). 

When the application is loaded and started, one of the first things it does is get its data 
files. The actual file names of the data files are usually specified in the application's 
description file, which is a file that may be read by using the OptionFile interface. The 
application gets its data files by using ApplicationFolder. FromName to obtain the 
ApplicationFolder file, using AppiicationFoider.FindDescriptionFile to get the description file 
from the ApplicationFolder file, and then using OptionFile.GetStringValue to get the data 
files names. (See Usage/Examples.) 

4.2 Interface Items 

FromName: procedure [internalName: xstring.Reader] 
RETURNS [applicationFolder: NSFiie.Reference]; 

Returns the folder for the given application. internalName is the section name in the 
description file. Returns NSFite.nullReference if not found. 

FindDescriptionFile: procedure [applicationFolder: NSFiie.Handle] 
RETURNS [descriptionFile: NSFiie.Reference]; 

Finds a file with file type = OptionFile (4385) in the applicationFolder. Returns 
NSFiie.nullReference if not found. 

EventData: TYPE » record [ 

applicationFolder: NSFiie.Reference, 
internalName: xstring.Reader]; 

The application loader also notifies the "ApplicationLoaded" event after loading and 
starting an application. EventData is passed as Event. EventData for this event. 
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4.3 Usage/Examples 

This example code obtains the message file. 

— File: SampleMsgFilefnitlmpl.mesa - last edit: 

— Copyright (C) 1985 by Xerox Corporation. All rights reserved. 
DIRECTORY 

AppiicationFolder using [FindDescriptionFile, FromName], 
Heap USING [systemZone], 

NSFile USING [Close, Error, GetReference, Handle, nullHandle, nullReference, OpenByName, 

Open By Reference, Reference, Type], 

NSString using [FreeString, String], 

OptionFile using [GetStringValue], 

SampieBWSApplicationOps, 

XMessage using [ClientData, FreeMsgOomainsStorage, Handle, MessagesFroniReference, 
MsgOonnains], 

XStrIng using [FromSTRING, NSStringFromReader, Reader, ReaderBody]; 

SampleMsgFilelmpi: program 

imports AppiicationFolder, Heap, NSFile, NSString, OptionFile, XMessage, XString 
EXPORTS SampieBWSApplicationOps > { 

-- Data 

h: xMessage.Handle «-nil; 

localZone: uncounted zone <- Heap.systemZone; 

— Procedures 

OeleteMessages: PROCEDURE [ciientOata: XMessage.ClientOata] s (}; 

GetMessageHandte: public procedure returns [xiyiessage.Handle] ■ {RETURN[h]}; 

InitMessages: procedure = { 

internalName: xstring.ReaderBody <-xstring.FromSTRING ["SampleBWSApplication"L]; 
msgDomains: XMessage.MsgDomains «~ nil; 
msgDomains *- XMessage.MessagesFromReference [ 

file: GetMessageFileRef [AppiicationFoider.FromName [@internalName]], 

ClientData: nil, 

proc: OeleteMessages ]; 
h <- msgDomains[01. handle; 
XMessage.FreeMsgDomainsStorage [msgDomains]; 

}; 

GetMessageFileRef: procedure [folder: NSFiie.Reference] 

returns [msgFile: NSFiie.Reference <-NSFiie.nullReference] « { ^ 
folderHandle: NSFiie.Handle NSFiie.OpenByReference [folder]; 
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internalName: xstring.ReaderBody xstring.FromsTRiNG ["SampleBWSApplication"L]; 
messageFiie: xstring.ReaderBody f- xstring.FromsTRiNG ["MessageFile"L]; 

FindMessageFileFromNatne: procedure [value: xstring.Reader] ■ { 

nssName: NSString.String <~xstring.NSStringFromReader [r: value, z: localZone]; 
msgFileHandle: NSFiie.Handle «-NSFiie.nuilHandie; 

msgFlleHandle <-NSFiie.OpenByName {directory: folderHandle, path: nssName ! 

NSFiie.Error ■ > {msgFileHandle <-NSFiie.nullHandle; continue}]; 
IF msgFileHandle ■ NSFile.nuilHandie then error; « no message file! 
msgFile NSFiie.GetReference [msgFileHandle]; 
NSFile.Close [msgFileHandle]; 
NSString.FreeString [z: localZone, s: nssName]; 

}; 

OptionFiie.GetStringValue [section: @internalName, entry: @messageFile, 

callBack: FindMessageFlleFromName, 

file: AppiicationFoider.FindOescriptionFile [folderHandle]]; 
NSFile.Close [folderHandle]; 

}; 

— Mainline code 
lnitMessages[]; 
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4.4 Index of Interface Items 

Item Page 

EventData: type 1 

FindDescriptionFile: procedure 1 

FromName: procedure 1 
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Overview 

Although it is often convenient to name an object using a textual name, XStrings are 
somewhat clumsy to compare and pass around. An atom is a one-word datum that has a 
one-to-one correspondence with a textual name. Using atoms, objects may be named 
textually without having to store, copy, and compare the strings themselves. Atoms were 
made popular by the Lisp language. 

The textual name associated with an atom is called its PName, just as it is in Lisp. If two 
atoms are equal, they correspond to the same PName and vice versa. An atom may also 
have properties associated with it; a property is a [name, valuel pair. 

Interface Items 

5.2.1 Making Atoms 

ATOM: TYPE[1]; 

null:. ATOM ■ loophole[0]. 

An ATOM is a one- word datum that has a one-to-one correspondence with a textual name, 
or PName. If two ATOMs are equal, they correspond to the same pName. If two pNames 
are equal, they correspond to the same ATOM. 

Make: procedure [pName: xstring.Reader] returns [atom: ATOM]; 

MakeAtom: procedure [pName: long string] returns [atom: ATOM]; 

MakeAtom and Make return the ATOM corresponding to pName, creating one if 
necessary. In pName, uppercase and lowercase characters are different and result in 
different ATOMs. The atom returned is valid for the duration of the boot session, and the 
pName is remembered for the duration of the boot session. 

GetPName: procedure [atom: ATOM] returns [pName: xstring.Reader]; 
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GetPName returns the name of atom, returning nil if atom is null. It raises the error 
NoSuch Atom if atom is not valid. 

3.2.2 Error 

NoSuchAtom: error; 

NoSuchAtom may be raised by GetPName, PutProp, GetProp, or RemoveProp. It is raised 
when an operation is presented with an ATOM for which no Make or MakeAtom operation 
has been done in the boot session. Such atoms are called invalid atoms. 

9.2.3 Property Lists 

Pair: type » record [prop: ATOM, value: RefAny]; 

Ref Any: type « long pointer; 

RefPair: TYPE ■ long pointer to readonly Pair; 

Pair defines the [name, value] pair for a property. Properties are named by atoms and have 
long pointers as values. Property pairs are referenced by a read-only pointer. 

PutProp: procedure [onto: ATOM, pair: Pair]; 

PutProp adds a property pair to onto. If the property already exists, the value is updated. 
If onto is null, no action takes place. PutProp raises the error NoSuchAtom if onto is not 
valid. 

GetProp: procedure [onto, prop: ATOM] returns [pair: RefPair]; 

GetProp returns the property pair whose property name is the atom prop from atom onto. 
If onto does not have a property whose name is prop or onto is null, nil is returned. 
GetProp raises the error NoSuchAtom if onto is not valid. Note: The client may not 
change the property pair. 

RemoveProp: procedure [onto, prop: ATOM]; 

RemoveProp removes the property pair whose property name is the atom prop from atom 
onto. If onto is null, no action takes place. RemoveProp raises the error NoSuchAtom if 
onto is not valid. 

5.2.4 Enumerating Atoms and Property Lists 

MapAtomProc: type ■ procedure [ATOM] returns [boolean]; 

MapAtomProc is used by MapAtom to enumerate atoms. When it returns true, the 
enumeration stops. 

MapAtoms: procedure [proc: MapAtomProc] returns [lastAtom: ATOM]; 
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MapAtoms enumerates the atoms, calling proc once for each atom. If proc returns true, 
MapAtoms returns that atom. If proc never returns TRUE, MapAtoms returns null. 

MapPListProc: TYPE « procedure [RefPair] returns [boolean]; 

MapPListProc is used by MapPList to enumerate property lists. When it returns TRUE, the 
enumeration stops. Note: The client may not change the property pair. 

MapPList: procedure [atom: ATOM, proc: MapPListProc] returns [lastPair: RefPair]; 

MapPList enumerates the property list of atom, calling proc once for each pair. If proc 
returns TRUE, MapPList returns that pair. If proc never returns true, MapPList returns nil. 

5.3 Usage/Examples 

Atom is most appropriately used for communicating names and permanent data between 
separate applications or between far-flung parts of a single application. The AtomicProfile 
interface is an example of this use. 

However, ATOMs and atom property lists add to the working set of every application, and 
thus degrade system performance as a whole. This happens because Atom must make a 
copy of the atom name in its (permanent) database, and every client of Atom uses that 
database. It is much better to keep an application's data separated from other data. 

Property lists are a shared, global resource and should be used for sharing other global 
resources. They should not be used for transient data. For example, consider the chaos that 
would ensue if several instances of an application were running simultaneously and each 
assumed that the property list of a particular atom was its to read and write. (Of course, 
this interference could also result from different applications running at different times.) 

ATOMs take a significant amount of time to create. Applications interested in good 
performance will only use ATOMs if they need a runtime-extendable enumeration; a 
simple compile-time enumeration is much more efficient. 

If you want an atom with a property list for a private or transient usage (a bad idea in any 
case) you must make sure that the atom is unique, so as not to interfere with other 
applications using the same atom. Code such as 

myList: Atom.ATOM » Atom.MakeAtom("string iisf'L]; - WRONG 

must be replaced by code that gives an atom name that is unique to the application or 
module (or instance, if multiple instances may be running). 

Two of the major uses of atoms are in the Event and TIP interfaces. In the Event interface, 
atoms name events. In the TIP interface they are used in TIP tables and TIP results to name 
actions. (See those interfaces for more information.) 
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The names of atoms are case sensitive. For example, atomi and atom2 are not equal, 
while atomi and atomS are equal. 

atomi: ATOM - MakeAtom["Atom"L]; 
atomZ: ATOM ■ MakeAtom["ATOM"L]; 
atom3:ATOM ■ Make[GetPName[atom1]]; 

The value of an atom is a function of the characters of its name and the names of the atoms 
that have been previously created. Atoms may not be pickled (put in a permanent 
representation that may be filed and recovered later) or transmitted to another system. 
The atom is just a convenient way to represent and manipulate the name, which is the 
permanent representation. 
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6.1 Overview 

The AtomicProfile interface provides a general mechanism for storinj^ and retrieving 
global values, such as user name and password. Values are named by atoms and may have 
a type of either boolean, long integer, or string. Only one value is associated with each 
atom, regardless of type. 

Boolean and long integer values are simple values, unlike string values, which are passed 
by reference. The value of strings may be gotten by calling the GetString routine, in which 
case they must be returned to the implementation using DoneWlthString. They may be 
gotten by using a callback procedure in EnumerateString. 

6.2 Interface Items 

6.2.1 Boolean Values 

GetBOOLEAN: procedure [atom: Atom .ATOM] returns [boolean]; 

GetBOOLEAN returns the boolean value associated with atom. If no boolean value is 
associated with atom, GetBOOLEAN returns false. 

SetBOOLEAN: procedure [atom: Atom.ATOM, boolean: boolean]; 

SetBOOLEAN associates the boolean value boolean with atom. If atom previously had 
another value associated with it, that value is replaced. The event AtomicProf ileChange is 
noticed, with event data being a long pointer to atom. 

6.2.2 Integer Values 

GetLONGINTEGER: procedure [atom: Atom.ATOM] returns [long integer); 

GetLONGINTEGER returns the long integer value associated with atom. If no long integer 
value is associated with atom, GetLONGINTEGER returns 0. 
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SetLONGINTEGER: procedure [atom: Atom.ATOM, int: long integer ]; 

SetLONGINTEGER associates the long integer value int with atom. If atom previously had 
another value associated with it, that value is replaced. The event AtomlcProf ileChange is 
notified, with event data being a long pointer to atom. 

6.2.3 String Values 

GetString: procedure [atom: Atom.ATOM] returns [ xstring.Reader]; 

GetString returns the string value associated with atom. The string is reference-counted, 
and the client must return the string by calling DoneWithString. If there is no string 
value associated with atom, GetString returns nil. 

DoneWithString: procedure [string: xstring.Reader]; 

A reader obtained by using GetString must be returned via DoneWithString so that the 
implementation's use-count will be correct. Failure to do so results in a storage leak if the 
value of the atom is replaced (see the example below). 

EnumerateString: procedure [ 

atom: Atom-ATOM, proc: procedure [xstring.Reader]]; 

EnumerateString provides an alternate method of examining the string value of an atom. 
If atom has a string value, proc is called with the string value, proc is called from within 
the monitor of the implementation. The reader is valid for the duration of the callback, but 
proc must not call any of the operations in the implementation. If atom has no string 
value, proc is not called. 

SetString: procedure [atom: Atom.ATOM, string: xstring.Reader, 
immutable: boolean <- false ]; 

SetString associates the string value string with atom. If atom previously had another 
value associated with it, that value is replaced. If immutable is false, SetString copies 
string's body and byte sequence; otherwise, it only copies the reader body. The client must 
not deallocate the byte sequence in this case. The event AtomicProfileChange is notified, 
with event data being a long pointer to atom. 

6.3 Usage/Examples 

AtomicProfile provides a general mechanism for storing and retrieving values. Actual use 
by a client depends on knowing the names and expected types of values. ViewPoint defines 
some basic values, such as user name and password. Other systems may define other 
values. 

In the following example, a client keeps track of the user name, which depends on the 
AtomicProfileChange event. UserNameChanged is called when any AtomicProfile value is 
changed. By examining the event data of the agent procedure, the example can act on 
changes to the user name. 
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atomicProfileChange: Atom.ATOM ■ Atom.MakeAtom[''AtomicProfiieChange"L]; 
fuiiUserName: Atom.ATOM > Atom.MakeAtom["FuliUserName"L]; 
debugging: Atom.ATOM ■ Atom.MakeAtom["Debugging"L]; 

UserNameChanged: Event. AgentProc » { 

atomChanged: LONGPOrNTERTOAtom.ATOM « eventData; 
IF atomChanged f ■ f ullUserName then { 
name: xstring.Reader ■ GetString[fuilUserName]; 
< < do processing of new name > > 

IF GetBOOLEAN[debugging] then {< < do debugging only code> >}; 
DoneWithString[namel}}; 

Event.AddOependency[ 

agent: UserNameChanged, myData: nil« event: atomicProfileChange]; 
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6.4 Index of Interface Items .^m^ 



lliClll 


'Pacta 


DoneWithString: procedure 


2 


EnumerateString: procedure 


2 


GetBOOLEAN: procedure 


1 


GetLONGiNTEGER: procedure 


1 


GetString: procedure 


2 


SetBOOLEAN: procedure 


1 


SetLONGINTEGER: procedure 


2 


SetString: procedure 


2 
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7.1 Overview 

The Attention interface provides a means for displaying messages to the user, [t 
implements a single window into which messages are displayed. In addition to displaying 
messages, the Attention window has a menu to which clients can add system-wide 
commands. 

There are three types of messages: simple messages, sticky messages, and confirmed 
messages. Simple messages have no special semantics. Sticky messages are redisplayed 
when a non-sticky message is cleared. Attention keeps track of one sticky message, 
''''•■i^ Confirmed messages ask for confirmation by the user. 

Attention allows messages to be logically appended. Each of the posting operations, Post, 
PostSticky, and PostAndConf irm, contains a boolean parameter clear. If clear is true, the 

window is cleared before the message is displayed. If not, the message is appended to the 
currently displayed message. This allows the client to use Attention to construct complex 
messages. 

Note that Attention works in concert with BackgroundProcess. If Attention is called from 
the Notifier process, the message is posted immediately in the attention window. If 
Attention is called from a non-Notifier process that has registered itself with the 
background manager by calling BackgroundProcess.ManageMe, then the background 
manager intercepts these messages and allows the user to see them later upon request (see 
BackgroundProcess for more details). This means that Attention can be called from any 

process at any time without worry . Fine point: In Viewpoint l.O, there was no background manager and 
the following restriction applied: The Attention interface could only be called from the Notifier process. 

To facilitate message construction, an XFormat.Handle is provided whose format procedure 
will post a simple message without clearing the window. See the example below and the 
XFormat chapter for more information. 

The Attention window has a global system menu. Operations are provided so that clients 
may add menu items to this menu, remove items from the menu, or swap items in the 
menu. 
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7.2 Interface Items jim^ 

7.2.1 Simple Messages 

Post: PROCEDURE [s: xstring.Reader, clear: boolean <~ true, beep: boolean false, 
blink: boolean false] ; 

Post displays the message s in the Attention window. If clear is true, it clears the 
Attention window before displaying s; otherwise, it displays S after whatever text is 
currently showing. Attention makes its own copy of the reader body and bytes of s. beep 
and blink stipulate that the corresponding feedback be presented to the user. 

Clear: procedure; 

Clear clears the Attention window of any simple message. If a simple message is being 
displayed and there is a current sticky message, the sticky message is displayed. Clear 
has no effect if a sticky message is being displayed. 

formatHandle: XFormat.Handle; 

formatHandle is an XFormat.Handle provided by the Attention window that clients can use 
to post simple messages. Its format procedure logically calls Post with clear being false. 
(See below for an example.) 

7.2.2 Sticky Messages 

Sticky messages are redisplayed when a non-sticky message is cleared. Attention keeps 
track of one sticky message. 

PostSticky: procedure [s: xstring.Reader, clear: boolean^ true, 
beep: boolean false, blink: boolean false]; 

PostSticky appends s to, or replaces, the current sticky message and then displays the new 
message in the window. Its operation is: (1) if the window has a simple message or clear, 
then clear the window; (2) if the window is clear, then clear the current sticky message; 
(3) append s to the current sticky message; and (4) display the new current sticky message. 
Attention makes its own copy of the reader body and bytes of s. beep and blink are the 
same as in Post above. 

ClearSticky: procedure; 

ClearSticky clears any current sticky message. If a sticky message is being displayed, the 
window is cleared. ClearSticky has no effect if there is no sticky message. 



7„2.3 Contirmation Messages 

PostAndConfirm: procedure [ 

s: xstring.Reader, clear: boolean <- true, confirmChoices: ConfirmChoices <-Inil, nil], 
timeout: Process.Ticks <-dontTimeout, 
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beep: boolean false, blink: boolean^ false] 
RETURNS [confirmed, timedOut: boolean]; 

ConfirmChoices: type « record [yes, no: xstring.Reader]; 

dontTimeout: Process.Tlclcs ■ 0; 

PostAndConfi rm acts like Post in displaying the message s but waits for confirmation by 
the user. The confirmChoices messages are displayed, and the user should select one of the 
choices with the mouse. If the user selects yes, confirmed is returned true; if no is selected 
or the STOP key is depressed, confirmed is returned false. If confirmChoices. yes # NIL and 
confrmChoices.no = NIL, then only confirmChoices.yes is posted and confirmCholces.no 
is ignored. This is useful for posting a message that the user must see, but for which the 
user gets no choice, such as "Unable to communicate with the printer: CONTINUE". 
PostAndConfi rm absorbs ail user input except the stop key and mouse actions over the yes 
and no messages. The client may specify a timeout value, which causes PostAndConfi rm 
to return confirmed false and timedOut true if the user does not act within timeout ticks. 
The default value dontTimeout disables this timeout feature. Attention makes its own 
copy of the reader body and bytes of s. 



7.2.4 System Menu 

AddMenultem: procedure [item: MenuOata.ltemHandiej; 
AddMenultem adds item to the global system menu. 
RemoveMenultem: procedure [item: MenuOata.ltemHandle]; 

RemoveMenultem removes item from the global system menu. There is no effect if item is 
not in the menu. 

SwapMenultem: procedure [old, new: MenuOata.ltemHandle]; 

SwapMenultem swaps new for oid in the global system menu. SwapMenultem[old: nil, 
new: item] is equivalent to AddMenultem(item: item] and SwapMenuitem[old: item, 
new: nil] is equivalent to RemoveMenultem[item: item]. 

7.3 Usage/Examples 

The following example has a client displaying the name and size of a file. The example 
uses the NSFile interface to access the file and get the name and size attributes. See the 
Services Programmer's Guide (610E00180): Filing Programmer's Manual for 
documentation on the NSFile interface. 

PostNameAndSize: procedure [file: NSFiie.Handle] » { 

nameSelections: NSFiie.Selections s [interpreted: [name: true]]; 

attr i butes : NSFiie.Att r i butes Record ; 

rb: xstring.ReaderBody «~ Message[theFile]; 

Attention.Post[s: @rb, clear: true]; - start a new message 

NSFiie.GetAttri butes [file, nameSelections, ©attributes); 

XFormat.NSString[Attention.formatHandie, attributes.name]; 

NSFiie.Clear Attributes [©attributes]; 
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XFormat.ReaderBody[h: Attention.formatHandle, rb: Message[contains]]; 
xFormat.Decimal[h: Attention.formatHandle, n: NSFiie.GetSizelnBytes[file]]; 
rb «- Message[bytes]; 

Attention.Post[s: @rb]}; " clear defaults to false 

Message: procedure [key: {theFile, contains, bytes}] returns [xstring.ReaderBody] a { 
...}; 

An example of the resulting message displayed in the Attention window is 

The file Foe contains 53324 bytes 

The example intermixes use of the format handle and use of the Post procedure. A client 
could clear first, using the Clear procedure, and then display the message by just using the 
format handle. Note: In a multilingual environment constructing a sentence from pieces 
like this is not recommended because the grammar of other languages could cause this 
sentence to be rather confusing. 
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7.4 Index of Interface Items 



Item Page 

AddMenuitem: PROCEDURE 3 

Clear: procedure 2 

ClearSticky: procedure 2 

ConfirmChoices: type 3 

dontTimeout: Process.Ticks 3 

formatHandle: XFormat.Handle 2 

Post: procedure 2 

PostAndConf i rm : procedure 2 

PostSticky: procedure 2 

RemoveMenultem: PROCEDURE 3 

SwapMeiiultem: procedure 3 
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8.1 Overview 

BackgroundProcess provides basic user feedback and control facilities to clients that want 
to run in a process other than the Notifier process (see the Notifier chapter). Once 
registered with BackgroundProcess, the client process can use Attention to post messages 
and check to see if the process has been aborted by the user. The user can look at the 
messages posted by the process and abort the process. Fine point: The impiemenLaiioa ot 
BackgroundProcess is a plug-in, so the user interface depends on a particular background manager. See 
ViewPoint friends-level documentation for details on how to build a background manager. 

8.2 Interface Items 

ManageMe: ManageProc; 

ManageProc: type = procedure [ 
name: xstring. Reader, 
cailBackProc: CaliBackProc, 
window: window.Handle 4-nil, 
icon: containee.DataHandle <-nil, 
context: long pointer nil, 
abortable: boolean false 
1 

RETURNS [finalStatus: FinaiStatus]; 

CailBackProc: type = procedure [context: long pointer] 
RETURNS [finalStatus: FinalStatus]; 

FinalStatus: type = machine dependent{ 

importantFailure(O), failure, quietSuccess, success, aborted, firstFree, last(15)}; 

A client process that wishes to be managed calls ManageMe. The client should already be 
in the process that it wishes to have managed; if the client starts in the Notifier, the client 
should do a fork and call ManageMe from the forked process, name is a string that the 
background manager may use to identify the process to the user. After ManageMe is 
called, the background manager calls cailBackProc with context to give control back to the 
client process. If the process is prepared to catch ABORTED, then abortable should be TRUE. If 
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the process is not prepared to catch aborted, then abortable should be false (see the 
Aborting Processes section below), window and icon may be provided for use by the 

background manager; if the process is tied to a particular window or icon, the background 
manager may use these to allow the user to manipulate the process via the window or icon. 
When the client process is completed or aborted, it should return from callBackProc with a 
f inalStatus Indicating the outcome of the process. importantFaiiure indicates that the user 
should be warned that the process terminated in a way that might need attention, failure 
indicates that the process failed in some way but that the user does not need to be 
informed in any special way. quietSuccess indicates that the process should go away 
without any final notice to the user, success indicates that the process succeeded and that 
a final status message may be posted, aborted indicates that the user aborted the process. 

UserAbort: procedure [process: process «. nullProcess] returns [boolean]; 

ResetUserAbort: procedure [process: process «■ nullProcess]; 

nullProcess: process s loophole(0]; 

UserAbort returns true if the user has requested that the process be aborted. 
ResetUserAbort clears any pending abort; if the user has requested an abort, UserAbort 
returns TRUE until ResetUserAbort is called or the process terminates.. If process is 
defaulted to nullProcess, both procedures assume that the current process is the process 
that called ManageMe. process should only be used if the process calling UserAbort or 
ResetUserAbort is different from the process that called ManageMe. 



8.3 Usage/Examples 
8.3.1 Posting Messages 



Once a client process has called ManageMe, it can freely post messages by using 
Attention. Fine point: the exact metliod by which the messages will be displayed is up to the background 
manager. Also, dnly the client process that originally called ManageMe can call Attention directly. If a 
background process has any associated subprocesses that need to use Attention to post messasjes, it must use a 
friends-level Attention interface to associate the subprocess with the client's main background process. 



8.3.2 Aborting processes 



If the user requests that a process be aborted, the background manager either calls 
Process.Abort (if ManageMe was called with abortable = true) and expects the client to 
catch the ERROR ABORTED, or (if ManageMe was called with abortable = false) sets a flag 
that the client can check by calling UserAbort. If ManageMe was called with abortable = 
false, the client process should periodically call UserAbort to see if the user has tried to 
abort the process. If the client does not check UserAbort, user attempts at stopping the 
process have no effect. 
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8.3.3 Example 

This example program illustrates the structure of a typical use of BackgroundProcess. A 
MenuProc is provided that can be called from the attention window. The MenuProc 
immediately forks a process, which reduces its priority, and then calls 
BackgroundProcess. The example program posts four messages, pausing between each 
and checking UserAbort on each pass. 

backgroundName: xstring.ReaderBody <-xstring.FromSTRING["Background Post"L]; 
abortedString: xstHng.ReaderBody <-xstring.FromSTRING["Process canceled ..."]; 

I nit: PROCEDURE => { 

Attention.AddMenultem [ 
MenuData.Createltem [ 
zone : z, -- some private zone 
name: ©backgroundName, 
proc: BackgroundProcessPost] ]; 

BackgroundProcessPost: MenuOata. MenuProc s { 

Process. Detach [fork OoBackgroundProces5Post[s: ©backgroundName]]}; 

OoBackgroundProcessPost: procedure [s: xstring. Reader] » { 
Dolt: BackgroundProcess.CailBackPrOC ■ { 

for i : cardinal in [1 ..4] do 

IF BackgroundProcess.UserAbortf] THEN { 

Attention.Post[@a bortedStri ng] ; 

RETURN[aborted]}; 
Attention.Post [s: s]; 
Attention.formatHandle.Blanks[2]; 
Attention.formatHandle.Decimai[i]; 
Process.Pause [Process.SecondsToTicks[1 0]] ; 

ENDLOOP; 

RETURN [success]}; 

Process.SetPriority[Process.priorityBackground]; 

[] ^-BackgroundProcess.ManageMe [name: @rb1,cailBackProc: Dolt]}; 
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8.4 Index of Interface Items 



Item Page 

CallBackProc: type 1 

FinalStatus: type 1 

ManageMe: procedure 1 

MangeProc: type 1 

nullProcess: process 2 

ResetUserAbort: procedure 2 

UserAbort: procedure 2 
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9.1 Overview 



The BlackKeys interface changes the interpretation of the main (central) section of the 
physical keyboard. It Includes the data structures that define a keyboard record as well as 
the procedures used to manipulate the keyboard stack. 

The average client uses only the data structures that the BlackKeys interface provides. 
The procedures are reserved for a keyboard manager interested in interfacing between the 
user and the blackkeys stack of keyboards. 



9.2 Interface Items 

9.2.1 Keyboard Data Structures 



The BlackKeys data structures provide the framework for client-defined keys in the main 
(central) section of the physical keyboard. This includes interface to a keyboard picture 
whose keytops may be selected with the mouse to simulate pressing the physical key on 
the keyboard. 

Keyboard: type s long pointer to KeyboardObject <- nil; 

KeyboardObject: type = record [ 
table: Tip.Table<- nil, 

charTransiator: TiP.CharTranslator ^[proc: nil, data: nil], 
pictureProc: PIctureProc «-nil, 
label: xstring.ReaderBody <- xstring.nuliReaderBody, 
clientOata: long pointer <-nil]: 

KeyboardObject is the keyboard interpretation data structure. The client may provide its 
own TIP. Table or default it to nil, in which case the NormalKeyboard.TIPtable is used. (See 
Appendix A for productions returned by NormalKeyboard.TIP). A TiP.CharTranslator may be 
provided to handle char and bufferedchar productions from a TiP.Table. A PictureProc may 

be provided to be called when installing or removing this keyboard. Absence of such a 
procedure assumes no picture is associated with this keyboard, label is the string that 
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appears in the SoftKeys window when the keyboard key is pressed down. Pressing (or 
selecting) the key marked label invokes this keyboard. clientData is provided to associate 
any other information the client might need to keep with the keyboard. 

PictureProc: type = procedure [ 
keyboard: Keyboard, 
action: PictureAction] 

RETURNS [ 

picture: Picture <- nullPicture, 
geometry: GeometryTable <-nil]; 

PictureProc is a client-provided procedure that is called by a keyboard window application 
when the client's keyboard is being installed (action = acquire) or removed (action = 
release) from the top of the blackkeys stack of active keyboards. The client may use this 
opportunity to map or unmap the picture and geometry table that the keyboard window 
application uses. 

PictureAction: type = (acquire, release}; 

acquire ■ client's keyboard is being installed at the top of the keyboard stack 
(becoming the current keyboard). 

release m client's keyboard is being removed from the top of the keyboard stack. 
PictureType: type = {bitmap, text}; 

Picture: TYPE s RECORD [ 

variant: select type: PictureType from 
bitmap a > [bitmap: long pointer], 
text s > [text: xstring. Reader] 
endcase]; 

The variant of the record, Picture, allows the client to present its keyboard window in 
either bitmap or textual form. (See the KeyboardWindow interface for a discussion of the 
structure behind a keyboard bitmap.) text is pointed to by an xstring.Reader. The text is 
not copied. 

nuliPicture: bitmap BiackKeys.Picture » [bitmap[NiL]]; 

The variable nullPicture represents a null entry to the keyboard window. 
GeometryTable: TYPE = long pointer; 

A geometry table allows access to the data structure. (See the KeyboardWindow interface 
chapter for discussion of the structure of a geometry table.) 

9.2.2 Getting a Handle to the Current Keyboard 

BlackKeysChange: Event.EventType; ATOM defmed as "BlackKeysChange" 
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Changing the keyboard at the top of the blackkeys stack of keyboards results in the 
notlHcation BlackKeysChange through the Event mechanism. The eventData supplied by 
the EventNotify is the current keyboard handle. 

GetCurrehtKeyboard: procedure returns [current: Keyboard]; 

GetCurrentKeyboard returns the current keyboard from the top of the blackkeys stack. 

9.2.3 Procedures 

Push: PROCEDURE [keyboard: Keyboard); 

The Push procedure installs a black key interpretation at the top of the blackkeys stack of 
keyboards. The TiP.Table and/or TiP.CharTranslator are registered with tip and the event 
BlackKeysChange is broadcast. 

Remove: procedure [keyboard: Keyboard); 

The Remove procedure removes the keyboard from the stack of active keyboards and 
resets the TiP.Table and TiP.CharTranslator as applicable. The event BlackKeysChange is 
broadcast if keyboard is on the top of the blackkeys stack. 

May raise the ERROR BiackKeys.lnvalidHandle. 

Swap: procedure [old: Keyboard, new: Keyboard]; 

The Swap procedure is designed to change black keys' interpretations without returning 
to some previous or other default value in between. It is essentially the equivalent of a 
Remove followed by a Push. The event BlackKeysChange is broadcast if the keyboard 
being removed was on top of the stack. 

May raise the error BiackKeys.lnvalidHandle. 

9.2.4 Errors 

InvalidHandle: error; 

This error is raised if the keyboard passed to Remove or Swap (old) is not in the set of 
active BlackKeys keyboards. 

9.3 Usage/Examples 

9.3.1 Defining a Keyboard Record 

DefineKeyboard: procedure = 

BEGIN 

nameStrIng: xstring.ReaderBody <- xstring.FromSTRING["Swahili"L] 

swahlliKeyboardRecord: BiackKeys.KeyboardObject ^ [ 

table: NIL, 

charlranslator: [MakeChar. nil). 
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pictureProc: MapBitmapFiie, 

label: xstring.CopyToNewReaderBody[@nameStrlng, Heap.systemZone]]; 
Save the pointer to the record somewhere for future use — 
END; -De/f'neKeyboard 

MapBitmapFiie: Black Keys.PictureProc a 

BEGIN 

pixPtr: BiackKeys.Picture.bitmap 4-BiackKeys.nuiiPicture: 
SELECT action from 

acquire = > 

{"Do the right thing to map the bitmap. Uses the default geometry table. 
RETURN[pixPtr, KeyboardWindow.defaultGeometry] }; 
release = > {—Do the right thing to unmap the bitmap — 
RETURNfBlackKeys.nullPi Cture, NIL] } 
ENO; - MapBitmapFiie 

MakeChar: TiP.KeyToCharProc = 

BEGIN 

-Map bufferedChar to desired xstring.Character - 
END; - MakeChar 
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9.4 Index of Interface Items 



Item Page 

BlackKeysChange: EventEventType 2 

GeometryTable: type 2 

GetCurrentKey board: procedure 3 

InvalidHandle: ERROR 3 

Keyboard: type 1 

KeyboardObject: type 1 

n U i i Pi Ctu re : bitmap Picture 2 

Picture: type 2 

PictureAction: type 2 

PictureProc: type 2 

Picturelype: type 2 

Push: PROCEDURE 3 

Remove: procedure 3 

Swap: procedure 3 
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10. 1 Overview 

BWSAttributeTypes defines the NSFlle.ExtendedAttributeTypes that are used by 
Viewpoint as well as the first NSFiie.ExtendedAttributeType available for client use. 

The only extended attributes defined here are the ones that can be attached to any file, 
such as mailing and filing application attributes. Attributes that are unique to a 
particular application's files should be defined privately within that application. Several 
applications can use the same extended attributes because application A should never be 
reading the attributes from application B*s files and vice versa. Fine point: Several application- 
specific attribute types are included in this interface for compatibility. 

The extended attributes that can be attached to any file, leaving a few spare ones for 
future use. are defined here. Also defined are the first available "application attribute" 
(firstAvailableApplicationType). Caution: An application should not use an extended 
attribute smaller than this one, nor should an application use an extended attribute larger 
than lastBWSType. 

10.2 Interface Items 

10.2.1 Available Application Types 

firstAvailableApplicationType: NSFiie.ExtendedAttributeType a . . . ; 
lastBWSType: NSFiie.ExtendedAttributeType a . . . ; 

Applications should only use the types in the range [firstAvailableApplicationType . . 
lastBWSType]. firstAvailableApplicationType is the first extended attribute type that 
applications can use to store application-specific attributes. Caution: An application 
should not use an extended attribute smaller than firstAvailableApplicationType. 
lastBWSType is the last extended attribute type that applications can use to store 
application-specific attributes. Caution: An application should not use an extended 
attribute larger than lastBWSType. 
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If a Viewpoint client needs more attributes than the number in this range, see the 
NSFiling group to obtain a range specific to that client. 

10.2.2 Viewpoint Types 

Consult the Mesa interface for the exact assignment of ViewPoint-speciflc types. 
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10.3 Index of Interface Items 

Item Page 

firstAvailableApplicationType: NSFiie.ExtendedAttributeType 1 

lastBWSType: NSFiie.ExtendedAttributeType 1 



10 BWSAttributeTypes 



10-4 



BWSFileTypes 



11.1 Overview 

BWSFileTypes defines several NSFile.Types used by ViewPoint. Applications should not use 
these types. (Also see the Catalog and Prototype interfaces.) 

ViewPoint clients must manage all file types that they use. Ranges of file types may be 
obtained from the Filing group. 

11.2 Interface Items 

root: NSFile.Type ■ . . . ; 

The root file of the volume has this type. The root has children that are called (by 
convention) catalogs. 

desktop, desktopCataiog: NSFile.Type ■ . . . ; 

The desktop catalog contains all the desktops on a workstation. An individual desktop has 
the same type as the desktop catalog. 

prototypeCatalog: NSFile.Type ■ . . . ; 

The prototype catalog contains prototype files for each application. A prototype file is a 
blank application file that the user can make copies of, such as Blank Folder, or Blank 
Document. (See the Prototype interface.) 

systemFlleCatalog: NSFile.Type ■ . . . ; 

The system file catalog contains system files, such as the beds for an application, message 
files, font files, TIP files,and so forth. (See the Catalog interface.) 
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11.3 Index of Interface Items 

Item Page 

desktop: NSFiie.Type 1 

desktopCatalog: NSFiie.Type 1 

prototypeCatalog: NSFiie.Type 1 

root: NSFiie.Type 1 

systemFiieCatalog: NSFiie.Type 1 
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12.1 Overview 

BWSZone defines several zones, each with different characteristics, that ViewPoint 
clients may use, as appropriate. 

12.2 Interface Items 

All zones are created at boot time and exist for the duration of the boot session. 
J permanent: UNCOUNTED zone; 

Permanent: procedure returns (uncounted zone] ; 

permanent is intended for nodes that are never deallocated. It has infinite threshold. 
Permanent returns permanent. 

logonSession: uncounted zone; 

LogonSession: procedure returns [uncounted zone]; 

logonSession is intended for nodes that last for a logon/logoff session. logonSession is 
emptied of all nodes at each logoff (that is, Heap. Flush). LogonSession returns 
logonSession. logonSession is created at boot time and is flushed at logoff. 

shortLlfetime: uncounted zone; 

ShortLifetime: procedure returns [uncounted zone]; 

shortLifetime is intended for nodes that are allocated for a very short time, such as during 
a notification. ShortLifetime returns shortLifetime. 

semipermanent: uncounted zone; 

^ Semipermanent: PROCEDURE RETURNS [uncounted zone]; 

semipermanent is intended for nodes that are allocated for a very long time but that might 
occasionally have to be expanded. Semipermanent returns semipermanent. 



12-1 



12 BWSZone 



12.3 Index of Interface Items 

Item Page 

LogonSession: procedure 1 

iogonSession: uncounted zone 1 

Permanent: procedure 1 

permanent: UNCOUNTED ZONE 1 

Semipermanent: procedure 1 

semipermanent: UNCOUNTED ZONE 1 

ShortLifetime: procedure 1 

shortLifeti me: UNCOUNTED ZONE 1 
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13.1 Overview 

Catalog manipulates files called catalogs that are direct descendants of the root file on a 
NSFiling volume. Each catalog is uniquely identified by its file type. Files can be opened 
and created within a catalog. Catalogs can be opened, created, and enumerated. 

Viewpoint creates a system file catalog and a prototype catalog (see the Prototype 
interface) at boot time. The system file catalog typically holds font files, TIP files, icon 
picture files, message flles,and so forth. 

13.2 Interface Items 

13.2.1 Finding and Creating Files in a Catalog 

GetFile: procedure [ 

catalogType: NSFiie.Type <-BWSFiieTypes.systemFileCatalog, 

name: xstring.Reader, 

readonly: boolean*- false, 

session: NSFiie.Session <-NSFiie.nuilSession] 

returns [file: NSFiie.Handle]; 

GetFile finds a file with name name in the catalog with type catalogType. If the file cannot 
be found, NSFile.nullHandle is returned. 

CreateFile: procedure [ 

catalogType: NSFiie.Type <-BWSFifeTypes.systemFlleCatalog, 

name: xstring.Reader, 

type: NSFiie.Type, 

isDirectory: boolean <- false, 

size: long cardinal ^0, 

session: NSFiie.Session ^NSFHe.nullSession] 

RETURNS [file: NSFiie.Handle]; 
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CreateFile creates a file with the specified attributes (name, type, isDirectory, size in 
bytes) in the catalog with type catalogType. 

13.2.2 Operating on Catalogs 

Open: procedure [ 

catalogType: NSFile.Type, 

session: NSFiie.Session 4-NSFiie.nullSession] 

RETURNS [catalog: NSFiie.Handlej; 

Opens the catalog with type catalogType. If the catalog cannot be opened, it returns 
NSFiie.nullHandie. 

Create: procedure [ 

name: xstring.Reader, 

catalogType: NSFile.Type, 

session: NSFiie.Session 4-NSFiie.nullSession] 

RETURNS [catalog: NSFiie.Reference]; 

Creates a catalog with the specified name and type. If the catalog already exists or cannot 
be created, it returns NSFile.nullReference. Note: Even though the file can be identified by 
type only, the name should be logical (such as "System Files") so that any tools written to 
manipulate catalogs can display these names. 

Enumerate: procedure [proc: CatalogProc]; 

CatalogProc: type ■ procedure [catalogType: NSFile.Type] 
returns [continue: boolean*- true]; 

Enumerate calls the client-supplied proc for each existing catalog or until proc returns 

FALSE. 

beforeLogonSession : NSFiie.Session ; 

beforeLogonSession is a session that can be used when calling a Catalog procedure before 
any user has logged on, such as at boot time. It is set to be the default session until a user 
logs on. 
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13.3 Index of Interface Items 



Item Page 

beforeLogonSession: NSFiie.Session 2 

CatalogProc: type 2 

Create: procedure 2 

CreateFile: procedure 1 

Enumerate: procedure 2 

GetFile: procedure 1 

Open: procedure 2 
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14.1 Overview 



Containee is an application registration facility. An application is a software package that 
implements the manipulation of one type of file. Containee is a facility for associating an 
application with a file type. 

14.1.1 Background 



All NSFiles have: 

• A name 

• A file type (long cardinal) 

• A set of attributes, such as create date 

• Either: 

• Content, such as a document 

• Children that are also NSFiles, such as a folder. 



An NSFlle that has children is often called a directory. Fine point: An NSFile can actually have both 
content and children; however, to simplify this discussion, this point is ignored. Because the children of an 
NSFile can themselves have children, NSFile supports a hierarchical file system. 

A Viewpoint desktop is backed by an NSFile that has children. Each child file of. the 
desktop's NSFile is represented on the screen by an iconic picture. 

Each application operates on NSFiles of a particular file type. For example, ViewPoint 
documents operate on NSFiles with file type of 4353. Each document icon is actually an 
NSFile of type 4353. Each application needs a way to register its ability to operate on files 
of a particular type. Containee is such a facility. 

14.1.2 Containee.Implementation 

An application's ability to operate on files of a particular type includes such operations as: 
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• Display of the iconic picture (full size and tiny) .^lii^ 

• Open, performed when the user selects an icon and presses OPEN 

• Properties, performed when the user selects an icon and presses PROPS 

• Take the current selection, performed when the user drops an object onto an icon 
by copying or MOVEing a selected object to an icon. 

An application registers itself by calling Containee.Setlmplementation, supplying a file 
type and a Containee.lmplementation. A Contamee.lmplementation is a record that contains 
two important procedures: 

• A procedure for displaying an icon picture (Containee.PictureProc) 

• A procedure for performing various operations on an icon, such as open, create a 
property sheet, and take the current selection (Containee.GenericProc). 

This application registration allows the ViewPoint desktop implementation to be open- 
ended. The desktop implementation itself does not know how any file behaves. Instead, it 
depends on applications registering their ability to operate on particular file types. The 
desktop implementation, at logon, simply enumerates the child files of the desktop's 
NSFile (using NSFile.Llst), obtaining the file type for each child. For each child file, the 
desktop implementation gets an application's Containee.impiementation by using the child 
file's file type (and Containee.Getlmplementation) and then calls that application's 
Containee.PictureProc to display an icon picture. Similarly, when the user selects an icon on 
the desktop and presses OPEN, the desktop implementation uses the file type of the file at 
that place on the desktop to get the application's Containee.lmplementation. It then calls Jiilli 
the application's Containee.GenericProc to get a StarWindowShell created. The 
implementations of Folders and File Drawers are similar to the desktop implementation 
in this respect. 

14.1.3 Containee.Data 

An application needs to distinguish one file from another. Two different documents may 
be the same file type but probably have different names and different contents. Whenever 
an application's Containee. DIspiayProc or Containee.GenericProc is called, the particular file 
being operated on by the user is passed to the procedure through the Containee.OataHandle 
parameter. A Containee.OataHandle is a pointer to a Containee.Data that is simply a record 
with an NSFile.Reference in it. An NSFiie.Ref erence uniquely identifies a particular file and 
allows the application to use various NSFiie file-accessing procedures for manipulating the 
file. 

14.2 Interface Items 

14.2.1 Items for Application Implementors 

Setlmplementation: procedure [NSFiie.Type, implementation] 
RETURNS [ Implementation]; 

Setlmplementation associates an Implementation record with a particular file type and 
returns the previous Implementation that was associated with that file type. An 
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application calls Setlmplementation to register its ability to operate on files of a 
particular type. 

implementation: TYPE ■ record [ 
impiementors: L0N6F0iNTER<-NiL, 
name: xstring.ReaderBody <-xstring.nullReacierBody, 
smaliPictureProc: SmaiiPictureProc ^nil, 
pictureProc:PlctureProc «- nil, 
convertProc: Selection.ConvertProc nil, 
genericProc:GenericProc<~NiL ]; 

When an application registers its ability to operate on files of a particular type (that is, 
calls Setlmplementation), it supplies an Implementation record. The Implementation 
record defines the behavior of all files of that type. 

impiementors is provided for the convenience of clients that may want to associate some 
application-specific data with the Implementation record. Note: This data is one per 
application, not one per file. 

name is a user-sensible name for the objects that the Implementation manipulates, such 
as "Document" or "Spreadsheet". This string typically comes from XMessage. The bytes of 
name are not copied-the storage for name must be allocated forever (which is easy to do 
by using XMessage). 

smaliPictureProc is a procedure of type SmaliPictureProc that returns a character. This 
procedure is described below, 

pictureProc is called whenever the file's full-sized icon picture needs to be painted. (See 
'W^ PictureProc.) 

convertProc is called to convert the file into another form, such as an Interpress master. 
This procedure is used when the owner of the current selection is a container, such as a 
folder, and the selection is actually a file (row) in the container. The owner of the selection 
(that is, the container implementation) may be called to convert the selected file (row), but 
only the application that implements that file's type can do the conversion. The 
convertProc allows the owner of the selection to pass the conversion request along to the 
application. The data parameter to the convertProc is a Containee.OataHandle. This 
convertProc does not need to be able to convert to a target type of file or filelype, but 
rather should call Contalnee.DefaultFlleConvertProc for these target types. If the 
application does not perform conversion to any target types, 
Containee.OefauitFileConvertProc should be provided as the convertProc. 

genericProc is where most of the application's real implementation resides. genericProc is 
called, for example, to open an icon, to produce a property sheet for an icon, to drop 
something on an icon,and so forth. (See GenericProc.) 

SmaliPictureProc: type = procedure [ 
data: DataHandle<-NiL, 
type: NSFiie.Type ignoreType, 
normalOrReference: PictureState] 
RETURNS [smallPicture: xstring.Character]; 

PictureState: type = { garbage, normal, highlighted, ghost, 
''*«^ reference, referenceHighlighted }; 
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ignoreType: NSFiie.Type = last[long cardinal] ; 

The SmallPictureProc returns a character for the application. It is obtained by passing a 
13xl3-bit icon picture to simpieTextFont.AddClientOefinedCharacter. This character is used 
when the file is inside a folder. normalOrReference will be either normal or reference, and 
the appropriate small picture should be returned. The SmallPictureProc should try to use 
the type parameter first if it is not Containee.ignoreType. If it is ignoreType, the 
SmallPictureProc should use the data parameter. This change is necessary to allow the 
reference icon application to work properly. Fine point: The picture for normalOrReference = 
reference/referenceHighlighted is not normally used by the folder application directly, but rather is used by a 
generic reference icon application. 

Data: type ■ record [ 

reference: NSFiie. Reference <-NSFiie.nullReference ]; 

OataHandle: TYPE s long pointer to Data; 

n ul I Data: Data; 

Data uniquely identifies a file. An application needs to distinguish one file from another. 
Two documents may be the same file type but probably have different names and different 
contents. Whenever an application's PictureProc or GenericProc or 
Implementation.convertProc is called, the particular file the user is operating on is passed 
to the procedure through the DataHandle parameter. An NSFile.Reference uniquely 
identifies a particular file and allows the application to utilize various NSFiie file- 
accessing procedures for manipulating the file. nullData is a constant that should be used 
to represent a null Containee.Data. 

GenericProc: type a procedure [ 

atom: Atom.ATOM, 

data: DataHandle, 
changeProc:ChangeProc «-NiL, 
changeProcData : long pointer nil] 

RETURNS [long UNSPECIFIED]; 

A GenericProc is a procedure supplied by an application as part of an Implementation. The 
GenericProc is called to perform one of several operations that a user can invoke, atom 
tells the GenericProc what operation to perform. For example, when the user selects an 
icon and presses the OPEN key, the application's GenericProc is called with an atom of 
Open is the one for which this application has registered its Implementation. 

A GenericProc must return a value. The type of the return value depends on the atom 
passed in. Some atoms, their meaning to the GenericProc, and the expected return values 
are as follows: 

Atom Return Value and Meaning 

Can YouTakeSelection long pointer to boolean 

If the application is willing to have the current selection 
dropped onto it, the GenericProc should return true. This 
occurs when the user has selected something, pressed COPY or 
MOVE, and then selected one of this application's files. While 
the mouse button is down, the cursor changes to a question 
mark if the GenericProc returns false; otherwise, the cursor 
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FreeMenu 



Menu 



Open 



Props 



TakeSelection 



stays the same and the icon picture flashes. This operation 
should be efficient. It usually involves calling 
Selection.CanYouConvert or Selection. HowHard or Selection. Query 
to determine what Selection.Targets the selected object can be 
converted to. For example, the printing application's 
GenericProc returns true if the current selection can be 
converted to an Interpress master. 

None 

The application should free the menu that was created for the 
Menu atom, if any. The MenuData.MenuHandie that was 
returned for the Menu atom is passed as the changeProcData. 
This atom is not passed to the GenericProc if the Menu atom 
returned NIL. The changeProc need not be called for this 
atom. 

MenuData.MenuHandie 

The application may create a menu that the system displays 
as a pop-up menu. This atom is passed when the user requests 
a pop-up menu for an icon—for example, by pressing both 
mouse buttons simultaneously while the mouse is over an icon 
on the desktop or in a container window. If the application 
returns a menu, then it should be prepared to free the menu 
when the FreeMenu atom is passed to the GenericProc. The 
changeProc need not be called for this atom. 

StarWindowShell.Handle 

The application shoiild create a StarWindowSheii. Usually, 
the content displayed in the StarWindowSheii is derived from 
the contents of the file. For example, the ViewPoint document 
editor application displays the text and graphics contained in 
the file, thus making the file ready for viewing, editing, or 
both. 

StarWindowShelLHandle 

The application should create a property sheet. Usually, the 
properties shown reflect some attributes of the file. For 
example, the Folder property sheet shows the name of the 
folder, how it is sorted, and how many objects it contains. 
These properties are all NSFile attributes of the file. 

LONG POINTER TO BOOLEAN 

The action performed for this atom is highly dependent on the 
particular application. This atom is passed when the user has 
selected something, pressed MOVE, and then selected one of 
this application's files. For some applications, the selected 
object should be moved into this application; for example, the 
Folder application converts the selected object to a file and 
adds the file to the folder. For other applications, the selected 
object should be operated on in some application-specific 
fashion—for example, the printing application converts the 
selected object to an Interpress master (file or stream) and then 
sends the master to a printer. The GenericProc should return 
TRUE if the operation was successful; false otherwise. 
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TakeSelectionCopy long pointer to boolean 

This atom has the same meaning as TakeSelection, except it 
corresponds to pressing the COPY key rather than MOVE. Again, 
its meaning is highly application dependent. 

The changeProc must always be called, passing in changeProcData and an indication of 
which NSFile attributes have changed, if any. If the execution of the GenericProc causes 
any change to the NSFIIe's attributes, calling the changeProc allows containers (such as 
Desktop or Folders) to update the display to reflect the changes. For example, when the 
atom is Props, the GenericProc must save the changeProc and return the 
StarWindowSheU.Handie for the property sheet. Then later, if the user changes the file's 
name, for example, the application's PropertySheet.MenultemProc gets control when the 
user is done and must then retrieve the changeProc and call it. (See the section on 
Usage/Examples for more detail.) 

If the client's GenericProc is called with an atom that it does not recognize, it should call 
the previous GenericProc (using the old Implementation that was returned when it called 
Containee.Setlmpiementation). The original system-supplied GenericProc acts to backstop 
all possible atoms. 

ChangeProc: type > procedure [ 

changeProcData: long pointer «- nil, 
data:DataHandle, 

changedAttributes: NSFiie.Selections *- [] 
noChanges: boolean false]; 

A ChangeProc is a callback procedure that is passed to a GenericProc. It must always be 
called by the client, regardless of whether an attribute of the file being operated has 
changed, to allow deallocation of the changeProcData. The noChanges boolean indicates 
the effect on the relevant file's attributes. The changeProcData parameter must be 
correctly supplied even for the noChanges = true case. It is used, for example, when the 
user changes the name of a file by using a property sheet. When the property sheet is 
taken down, the application changes the file's name and the ChangeProc that was passed 
to the GenericProc must then be called by the application. (See more detail in the section 
on Usage/Examples.) 

PictureProc: type ■ procedure ( 
data:DataHandie, 
window: window.Handle, 
box: Window. Box, 
old, new: PictureState ]; 

PictureState: type « {garbage, normal, highlighted, ghost, reference, referenceHighlighted}; 

A PictureProc is a procedure supplied by an application as part of an Implementation. The 
PictureProc is called whenever the desktop implementation needs to have the application's 
Leon picture repainted or painted differently. 

data identifies the particular NSFile whose picture should be painted. The NSFIIe's file type 
is the one for which this application has registered its Implementation. Even though all 
files of the same type have the same PictureProc and therefore the same-shaped picture, 
each picture differs because the name of the NSFile is often displayed on the picture. An 
application's PictureProc can obtain an NSFIIe's name by using NSFile operations, but may 
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more easily obtain it by using Containee.GetCachedName. This is one of the primary 
intended uses for GetCachedName. (See the section on Attribute Cache.) 

window and box should be passed to any display procedures used to paint the icon picture, 
such as Oisplay.Bitmap and SimpieTextoisplay.StringlntoWindow. 

The old and new arguments describe the current and desired states of the icon picture, 
garbage is the unknown state. PictureProc is called with new ■ garbage before moving or 
otherwise altering the icon; this lets an application remember an icon's placement. The 
application can thus continually update the icon (for example, to represent time of day) or 
can force a repaint by using window.lnvalidate (to change the shape of an InBasket icon, for 
example), normal is the picture displayed when the icon is not selected, highlighted is the 
picture displayed when the icon is selected, ghost is the picture displayed when the icon is 
currently open, reference is the picture displayed to represent a remote file. 
referenceHighlighted is the highlighted version of reference. The desktop 
implementation never uses these last two states, but a generic reference icon application 
might. 

OefaultFileConvertProc: seiection.ConvertProc; 

OefaultFileConvertProc is a Selection.ConvertProc that knows how to convert to 
Selection. Targets of file and fileType. OefaultFileConvertProc should be called from an 
application's Implementation.convertProc for these targets, or should be provided as the 
application's Implementation.convertProc if the application has no convertProc of its own. 
No file-backed application's convertProc should need to worry about these target types. 

14.2.2 Items for Application Consumers 

These items are not ordinarily used by an application implementation (provider), but 
rather by a consumer such as the Desktop or Folder implementation. 

Getlmplementation: procedure [NSFiie.Type] returns [Implementation]; 

Getimpiementation returns the current Implementation for a particular file type. 

14.2.3 Defaultlmplementation 

Containee supports a single global default Implementation. This default Implementation is 
used when the user operates on an NSFiie for which no Implementation has yet been 
registered. 

GetOefaultimplementation: procedure returns [Implementation]; 

GetOefaultlmplementation returns the current default Implementation. 

SetDefaultlmplementation: procedure [implementation] 
RETURNS [ implementation]; 

The default implementation provides a dummy display and appropriate "Sorry, Desktop is 
Unable to Open That Object" complaints in the absence of a particular implementation. 
Most clients do not call SetDefaultlmplementation. 
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14.2.4 Attribute Cache i****^ 

Clients often want to use several common NSFile.Attributes. However,. it is awkward to pass 
the attributes around in calls because the attributes are long, of variable length, and 
frequently not needed by the called routine. Therefore, Containee provides a cache 
mechanism that can remember and supply popular attributes. Currently, the name and 
file type attributes are supported. Containee decouples the management of in-memory 
copies of a file's name from parameter-passing arrangements. 

GetCachedName: procedure [data:DataHandle] 
RETURNS [name: xstring.ReaderBody, ticket:Ticket]; 

GetCachedName returns the name attribute of the NSFile referred to by data. If the name 
is not in the cache, it is looked up and added to the cache, ticket must be returned (by using 
ReturnTicket) when the client is through with the name. The ticket prevents one client 
from changing the name while another is looking at it. 

GetCachedType: procedure [data:OataHandle] 
RETURNS [type:NSFiie.Type]; 

GetCachedType returns the type attribute of the NSFile referred to by data. If the type is 
not in the cache, it is looked up and added to the cache. 

InvalidateCache: procedure [data:DataHandle] ; 

InvalidateCache clears any information about the NSFile from the cache. It is typically 
called when the attributes of an NSFile are changed by an application. An application 
rarely needs to call InvalidateCache, because calling the ChangeProc takes care of it. 

InvalidateWholeCache: procedure ; 

InvalidateWhoieCache clears the entire cache. Information about all files is cleared. 
ReturnTicket: procedure [ticket: Ticket]; 

ReturnTicket should be called after calling GetCachedName, when the client no longer 
needs the string. 

SetCachedName: procedure [data: Data Handle, newName: xstring.Reader]; 

SetCachedName allows a client to change a cached name. Care should be taken to keep 
the filed name consistent with the cached name. An application rarely needs to call 
InvalidateCache, because calling the ChangeProc takes care of it. 

SetCachedType: procedure [data:OataHandle, newType:NSFiie.Typel; 

SetCachedType allows a client to change a cached type. Care should be taken to keep the 
filed type consistent with the cached type. 

Ticket: type(21; 
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A Ticket is returned when GetCachedName is called. When the client is through using the 
cached name, the ticket must be returned by calling ReturnTicket to prevent one client 
from changing the name while another is looking at it. 

14.3 Errors and Signals 

Error: error [msg: xstring.Reader ^ nil, error: error *- nil, 
error Data: long pointer to unspecified nilI; 

Signal: signal [msg: xstring.Reader nil, error: error «- nil, 
errorOata: long pointer to unspecified *- wi]; 

An application's GenericProc (and PictureProc and ConvertProc) should never assume that 
it has been called by a desktop and therefore should never call such facilities as 
Attention. Post or UserTerminal.BlinkDisplay. (The application might be called by CUSP, for 
example.) Rather, the application should raise Containee. Error or Signal with an 
appropriate message. Containee will not catch these errors. The caller of the application's 
GenericProc should catch them and do the appropriate thing. In the typical case, the 
ViewPoint desktop calls the application's GenericProc; it catches the error and calls 
Attention.Post with the passed message. CUSP could catch the error and log the message in 
a log file. 

msg is the message to display to the user, error is the actual lower-level error that ocurred 
that caused Error or Signal to be raised. errorOata points to any additional data that 
accompanied the lower-level error. 

14.4 Usage/Examples 

14.4.1 Sample Containee 

The folder application is used as an example of a simple application that implements a 
particular file type. 

- Constants and global data 

folderFilelype: NSFiie.Type ■ . . 
oidimpi: Containee.lmplementation []; 

- Containee.lmplementation procedures 

FolderGenericProc: Containee.GenericProc ■ 
< < [atom: Atom.A TOM, 

data: containee. DataHandle, 

changeProc: ContaineeXhangeProc <-nil, 

changeProcData : long pomter *- nil] 

RETURNS [long UNSPECIFIED] > > 
BEGIN 

SELECT atom FROM 

open ac > return [MakeFolder[data, changeProc, changeProcOata] ]; 
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props ■ > RETURN [MakePropertySheet[data,changeProc, changeProcData] ]; 
canYouTakeSelection ■ > return [ if CanlTake[changeProc, changeProcData] 

THEN @true ELSE @false]; 
takeSeiection > > return [if Take[data, move, changeProc, changeProcOata] then 

©true ELSE ©false]; 

takeSeiectionCopy > > return [if Take[data, copy, changeProc, changeProcOata] 

THEN @true ELSE ©false ]; 
menu « > 

BEGIN 

run: xstrlng.ReaderBody ♦-xstring.FromSTRING ["AltOpen"L]; 
name: xstring.ReaderBody <-xstring.FromSTRING ["Folder"L]; 
title: MenuData.itemHandle <-MenuOata.Createitem[ 

zone: nil, name: ©name, proc: nil]; 
items: array[0..1} of MenuData.itemHandle <- [ 

MenuOata.Createltem[zone: nil, name: ©run, proc: AltOpen]]; 
menu: MenuOata.MenuHandle <— MenuData.CreateMenu[ 

zone: nil, title: title, array: DESCRiPTOR[items]]; 
RETURN [menu]; 
end; 
freeMenu ■ > 
begin 

menu: MenuOata.MenuHandle changeProcOata; 
MenuData.OestroyMenu [NIL, menu]; 
RETURN[menu]; 
end; 

endcase ■ > return [ 

oldlmpl.genericProc [atom, data, changeProc, changeProcOata] ]; 

end; 

AltOpen: MenuData.MenuProc ■ {...}; 

CanlTake: procedure [ 

changeProc: Containee.ChangeProc «-nil, 
changeProcOata: long pointer*- nil] 
returns [yes: boolean] » { 

< < Use Selection.CanYouConvert to see if the current selection can convert to a 
file. If so, then return TRUE, else FALSE. > > 

}; 

MakeFolder: procedure [ 
data: Containee.OataHandie, 
changeProc: Containee.ChangeProc ♦-nil, 
changeProcOata : long pointer <- nil] 

returns [shell: StarWindowShell.Handle] ■ { 

< < Create and return a StarWindowShell containing a list of the files in this folder. 
Use FileContainerSheil.Create. >> 

}; 

MakePropertySheet: procedure [ 
data: Containee.OataHandie, 
changeProc: Containee.ChangeProc «- nil, 
changeProcOata: long pointer <- nil] 
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RETURNS [psheet: StarWindowShell.Handle] a { 

< < Create and return a property sheet, using PropertySheetXreate. > > 

}; 

Take: procedure [ 

data: Containee.DataHandle, 
copyOrMove:Seiection.CopyOrMove, 
changeProc: containee.ChangeProc «-niu 
changeProcOata: long pointer «- nil] 
RETURNS [ok: boolean] ■ { 

< < Convert the current selection to a file using Seiection.Convert or 
Selection.Enumerate, and copy or move that file into this folder. > > 

}; 

- Initialization procedures 

InitAtoms: procedure « { 

open *-Atom.MakeAtom["Open"Ll; 
props <-Atoni.MakeAtom("Props"L]; 

canYouTakeSelection <-Atoin.MakeAtom("CanYouTakeSelection"L]; 
takeSelection4~Atom.MakeAtom["TakeSelection"L]; 
takeSelectionCopy ^ Atom.MakeAtom["TakeSelectjonCopy "L]; 
menu <-Atom.MakeAtom('*Menu"L]; 
freeMenu<-Atom.MakeAtom["FreeMenu"L]; 

}; 

Setlmplementation: procedure a { 

newlmpi : Containee.lmpiementation containee.Getlmplementation [ 

folderFileTypeJ; 
newimpi.genericProc <- FolderGenericProc; 

oldlmpi «-Containee.Setlmplementation [folderFiieType, newlmpi ]; 

}; 

- Mainline code 
InitAtomsd; 
Setimptementation[]; 

14.4.2 ChangeProc example 

The folder property sheet is used to demonstrate a callback to a ChangeProc. 

DataObject: TYPE ■ record [ 
fh: NSFiie.Handle, 

changeProc: containee.ChangeProc ♦-nil, 
changeProcOata: long pointer nil]; 

Data: TYPE > long pointer to DataObject; 

MakePropertySheet: procedure [ 
data: containee.DataHandle, 
changeProc: Containee.ChangeProc ^ nil, 
changeProcData : long pointer *- nil] 
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RETURNS [pSheetShell: starWindowSheii.Handle] ■{ 

- Pass changeProc to Makeltems through ciientData. 

mydata: Data <- zone.NEW[DataObject «~ [ 
f h : NSFile.OpenByRef erence[@data.ref erence], 
changeProc: changeProc, 
changeProcData : changeProcData]] ; 

pSheetShell ^ propertySheet.Create ( 
formWindowttems: Makeltems, 
menuitemProc: MenultemProc, 
menultems: [done: true, cancel: true, defaults: true], 
title: XMessage.Get [...], 
formWindowltemsLayout: OoLayout, 
display: false, 
ciientData: mydata]; 

}; 

Makeltems: Formwindow.MakeltemsProc a { 

— Make property sheet items with cails to FormWindow.MakeXXXItem. 

}; 

MenuitemProc: PropertySheet.MenuitemProc ■ { 

< < [shell: starwindowSheiLHandle, formWindow: Wmdow.Handle, .^til'iiik 

menultem: PropertySheet.MenultemType, ciientData: long pointer] 

RETURNS [destroy: boolean «- false] > > 
mydata: Data « ciientData; 
select menultem from 

done ■ > RETURN [destroy: ApplyAnyChanges[formWindow, mydata].ok]; 

cancel a > RETURN[destroy: true]; 

defaults * > . . . 

endcase; 
RETURN[destroy: false); 

}; 

ApplyAnyChanges: PROC[fw: window.Handle, mydata: Data] returns [ok: boolean] ■ { 
" Collect any changes in the property sheet items. 
NSFiie.ChangeAttributes [mydata.fh, ...]; 

BEGIN Call the changeProc. 

data: containee.Data <- [ NSFUe.GetReference [mydata.fh] ]; 
IF mydata.changeProc # nil then 

mydata.changeProc[mydata.changeProcData, @data,changedAttributes]; 
end; 



RETURN [ok: true]; 

}; 
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14.4.3 Error and Signal Usage 

This client catches an NSFile.Error and raises Containee. Error, passing along the ERROR and 
the NSFile.ErrorRecord: 

message: xstn'ng.ReaderBody; 
errorRecord: NSFile.ErrorRecord; 
signal: -GENERIC-- signal nil; 
file <~NSFiie.OpenByReference [reference: ... ! 

NSFile.Error ■ > { 
errorRecord <- error; 
signal <~LOOPHOLE[NSFiie.Error, signal]; 
GOTO ErrorExit}!; 
< < Operate on the file.>> 
NSFiie.Close[fiiel; 

EXITS 

ErrorExit ■ > { 
message 4~xstring.FromSTRING["NSFiie.Error"L]; 

Containee.Error [msg: ©message, error: signal, errorOata: ©errorRecord]; 
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14.5 Index of Interface Items 

Item Page 

ChangeProc: type 6 

Data: type 4 

DataHandie: type 4 

OefauitFileConvertProc: Seiection.ConvertProc 7 

Error: ERROR 9 

GenericProc: type 4 

GetCachedName: procedure 8 

GetCachedType: procedure 8 

GetDefaultimplementation: procedure 7 

Getimplementation: procedure 7 

ignoreType:NSFile 4 

Implementation: type 3 

InvalidateCache: procedure 8 

InvaiidateWhoieCache: procedure 8 

nuilData:Oata 4 

PictureProc: type 6 

PictureState: type 3 

PictureState: type 6 

ReturnTicket: procedure 8 

SetCachedName: procedure 8 

SetCachedType: procedure 8 

SetDefaultimplementation: procedure 7 

Setlmplementation: procedure 2 

Signal: SIGNAL 9 

SmallPictureProc:TYPE 3 

Ticket: type 8 
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15.1 Overview 

The ContainerCache interface provides the writer of a ContainerSource with a cache for 
the container's items. ContainerCache supports storing strings and client data with each 
item. 

15.2 Interface Items 

15.2.1 Cache Allocation and Management 

Handle: type = long pointer to Objects- 
Object: type; 

AllocateCache2: procedure [useProcessAbort: boolean <~ true] returns [Handle]; 

AllocateCache2 returns a handle on a cache that can be filled with BeginFill. The client 
should call ResetCache before calling BeginFill. useProcessAbort indicates whether 
Process.Abort should be raised by ContainerCache when the fill process is aborted--for 
example, when the cache is destroyed while still filling. It is intended to accommodate 
clients that cannot properly handle ABORTED. AllocateCacheZ is actually in 
ContainerCacheE xtra2. mesa. 

AllocateCache: procedure returns [Handle]; 

AltocateCache returns a handle on a cache that can be filled with BeginFill. The client 
should call ResetCache before calling BeginFill. 

GetLength: procedure [cache: Handle] returns [cacheLength: cardinal]; 

GetLength returns the number of items in the cache. GetLength is actually in 
ContainerCacheExtra.mesa. 

ResetCache: procedure [Handle]; 
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ResetCache clears the cache so that, for example, the cache can be refilled by calling 
BeginFill. 

FreeCache: procedure [Handle]; 

Frees the resources used by a cache. 

15.2.2 Filling the Cache 

The client initially fills a cache with items by calling BeginFill with a FillProc. The FillProc 
adds items to the cache by repeatedly calling Appendltem. 

FillProc: type = procedure [cache: Handle] 

RETURNS (errored: BOOLEAN <-FALSE]: 

The client provides a FillProc to the BeginFill procedure. The FillProc should fill the cache 
by using Appendltem. errored an indication of whether an error occurred during the 
filling of the cache (errored * true). 

BeginFill: procedure [ 
cache: Handle, 
fillProc: FillProc, 

clients: long pointer, 

fork : BOOLEAN <- TRUE ] ; 

Clients: procedure [cache: Handle] 
RETURNS [clients: long pointer] ; 

BeginFill begins filling the cache. fillProc is called to add items to the cache. If fork is true, 
then fillProc is forked as a separate process, clients is stored with the cache and may be 
retrieved by calling Clients. 

CacheFillStatus: type = {no, inProgress, inProgressPendingAbort, 
inProgressPendingJoin, yes, yesWithError, spare }; 

StatusOfFill: procedure [cache: Handle] 
returns [CacheFillStatus]; 

StatusOfFill returns the current status of the cache fill, yes indicates that the fill has 
successfully completed; no means the cache has not been filled yet; inProgress indicates 
that the fill is running right now. inProgressPendingAbort indicates that an abort has 
been received but the fillProc has not yet returned. inProgressPendingJoin, yesWithError, 
and spare are not currently used. 



15.2.3 Item Operations 

ItemHandle: type = long pointer to ItemObject; 
ItemObject: type: 
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AddData: type = recoro( 

clientData: long pointer, - TO ARRAY [0..0) OF WORD 
ciientDataCount: cardinal, 

clientStrings: long descriptor for array of xstring.ReaderBody]; 

An AddData record is passed to the Appendltem, Insertltem, and Repiaceltem procedures. 
clientOata should contain any data that the client wants to cache with the item, usually 
some type of reference to the actual item. ciientDataCount is the size (in words) of the 
clientData. clientData is copied into the cache; therefore the clientData should contain no 
pointers to other data. clientStrings should contain the strings to be displayed for the item. 
clientStrings are also copied into the cache, allowing the client to free them. 

The standard use of clientStrings is to implement the ContainerSource.StringOfltemProc, 
which can be accessed efficiently by using ItemNthString. (See the section on item content 
operations for more details on accessing the contents of items.) Caution: There are 
restrictions on the total length of an item (strings plus client data) that may be added to a 
cache. Currently, no item should be longer than 512 bytes. 

Appendltem: procedure [ 
cache: Handle, 
addData: AddData] 
returns [handle :itemHandle]; 

Appendltem appends an item to the end of cache. It is usually called repeatedly from 
within a FiiiProc. handle is a pointer that can be used to access the new item. 

DeleteNltems: procedure [ 
cache: Handle, 
item: cardinal. 
nitems: cardinal <-i]; 

DeleteNltems deletes one or more consecutive items from cache, starting at item. Fine point: 
Because the cache is maintained as a c'ontiguous string of bits, this operation is likely to be slow compared to 
Appendltem and GetNthltem. 

GetNthitem: procedure [cache: Handle, n: cardinal] 
returns [ItemHandle]; 

GetNthltem returns the nth item in cache. The items are numbered from zero. It returns 
NIL if no such item exists. The ItemHandle returned is not guaranteed to be valid after any 
operation that modifies the cache (DeleteNltems, Insertltem, Repiaceltem). If the cache 
status is inProgress (if someone is in the process of filling the cache), GetNthltem does not 
return until the nth item has been appended to the cache or until the fill is complete. 
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I nsertltem : procedure [ 
cache: Handle, 
before: cardinal, 
addData: AddData] 
RETURNS [handle: ItemHandle]; 

I nsertltem inserts an item in cache. The new item is inserted before the item before. Note 
that all the items after this item will be renumbered. Fine point: Because the cache is maintained 
as a contiguous string of bits, this operation is likely to be slow compared to Appendltem and GetNthltem. 

Replaceltem: procedure [ 
cache: Handle, 
item: cardinal, 
addData: AddData] 
RETURNS [handle: ItemHandlej; 

Replaceltem replaces the contents of item in cache with the information in addData. Fine 

point: This operation is implemented as DeleteNitems t'ollowed by Insertltem, and so is likely to be slow compared 
CO Appendltem and GetNthltem. 

15.2.4 Item Content Operations 

Itemlndex: procedure [item: ItemHandle] returns [index: cardinal]; 

Given the handle item, Itemlndex returns its index in the cache. Jllfc 

ItemClients: procedure [item: ItemHandle] returns [clientData: long pointer]; 

Returns the client data associated with item. If the client data passed in was NIL, 
clientData is NIL. 

ItemClientsLength: procedure [item: ItemHandle] returns [dataLength: cardinal]; 
Returns the length of the client data passed in with item. 
ItemStringCount: procedure [item: ItemHandle] returns [strings: cardinal]; 
Returns the number of client strings associated with item. 

ItemNthString: procedure [item: ItemHandle, n: cardinal] returns [xstring.ReaderBody]; 

Returns the nth client string associated with item. This operation can be used to 
implement a ContainerSource.StringOfltemProc . 

15.2.5 Marking Items in the Cache 

Whenever items are deleted or inserted in a ContainerCache, all the items are 
renumbered. This allows a client to keep track of items by marking them. ContainerCache 
keeps track of the marked items across any changes to the cache. A mark is a handle on a J^ll 
cache item that tracks the item when the item number changes. This facility is handy for 
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container source implementations that use ContainerCache and want to perform all the 
various combinations of moving and copying items within the source. 

Mark: type ».long pointer to MarkObject; 
MarkObject: type; 

SetMark: procedure [ 

cache: ContainerCache.Handie, index: cardinal] 
RETURNS (mark: Mark]; 

- set a mark at index 

IndexFromMark: procedure [mark: Mark] 
RETURNS [index: cardinal); 
-- get the current value of this marl( 

MoveMark: procedure (mark: Mark, newlndex: cardinal); 

— allows the resetting of a mark without using a new one 

FreeMark: procedure [mark: Mark); 
" mark no longer needed 

15.3 Usage/Examples 

After the client allocates a cache, the client starts filling the cache by calling BeginFill 
with a FillProc. BeginFill immediately calls the FillProc. Inside the FillProc, the client 
usually does some kind of enumeration on the source backing (for example, if the source is 
backed by files, the client does an NSFHe.Llst). For each item enumerated by the FillProc, the 
client builds the required strings for that item and then passes the strings along with any 
item data to Appenditem. The item data is usually some information that is needed to 
identify the item uniquely (for the file example, this might be a file ID). This process 
continues until all the items in the source have been enumerated, at which time the 
FillProc returns. 

The call to BeginFill may indicate that the FillProc should be forked into a separate process. 
This allows the enumeration of the source's items to go on in the background, which is an 
advantage if the source has a large number of items. If the source is being displayed in a 
ContainerWindow while this background fill is taking place, the window displays each 
new item as it is appended to the cache. Fine point: ContainerWindow can display the items as they 
are added because GetNthltem will wait during the flUing of the cache until the requested item is in the cache 
instead of returning with an indication that the requested item is not available. 

Once the cache has been created, operations on the container source that owns the cache 
may cause items in the cache to become invalid. One way to bring the cache back into 
synch is to invoke BeginFill and rebuild the cache. If reenumerating the items in the 
source is expensive, items in the cache can be updated with the operations OeleteNltems, 
Insertltem, and Replaceltem. The disadvantage of these operations is that they may cause 

performance degradation. Fine Point: The current implementation tries to maintain the cache as a 
contiguous series of strings of bits to minimize swapping. Using these operations may move large amounts of data 
around or fragment the cache data. If a large number of changes are to be made, it may pay to rebuild the cache. 
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Use of ContainerCache may not always be appropriate. In some cases, the structure of 
items in a source may be simple enough that a simple data structure may suffice to hold 
all the information necessary to respond to source operations. 

15.3.1 Example of ContainerCache Use 

The following example is taken from the implementation of FileContainerSource. It gives 
an example FillProc that uses Appendltem to build the cache. 

ReaderSeq: TYPE = record [sequence length: cardinal of xstring.ReaderBody]: 
ReaderSeqPtr: type = long pointer to ReaderSeq: 

WriterSeq: TYPE = RECORD [SEQUENCE length: CARDINAL OF XString.WHterBody]; 

WriterSeqPtr: type » long pointer to WriterSeq; 

FillCachelnBackground: ContainerCache. FillProc = 

<< [cache: Handle] RETURNS [errored: BOOLEAN <~ FALSE] > > 

BEGIN 

fs: FS <~containerCache.Cllents[cache]; — get container source context 
parentHandle: NSFiie.Handle; 

writers: WriterSeqPtr <-AllocateWriters [fs. columns. lengths- 
readers: ReaderSeqPtr <- z.NEW [ReaderSeq[fs.coiumns.iength]]; 

Enumerator: NSFiie.AttributesProc = 

BEGIN 

itemOata: ItemFileData; 
addOata: ContainerCache-AddData; 

addOata BuildRow [fs, writers, readers, @itemData, attributes]; 

[] 4-ContainerCache.Appendltem [cache, addData]; 

return; 

end; 

BEGIN 

parentHandle «~NSFiie.OpenByReference [fs.parentReference]; 
Process-SetPriority [Process, priority Background]; 
NSFiie.List [ directory: parentHandle, proc: Enumerator, 

selections: fs.selections, scope: fs.scope ]; 
NSFiie.Close [parentHandle]; 
end; 

z.FREE [©readers]; 
FreeWriters [writers]; 

return; 
end; 

BuildRow: procedure [ 

fs: FS, 

writers: long pointer to WriterSeq, jflHi 
readers: long pointer to ReaderSeq, 
itemOata: ItemFileOataHandle, 
attributes: NSFile.Attributes] 
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RETURNS [addData: ContainerCache.AddData] ■ 

BEGIN 

attr: NSFiie.Attribute; 

ci: Containee.lmpiementation; 

ci <~Containee.Getlmpiementation [attributes.type]; 
FOR i: CARDINAL IN [O..fs.coiumns.length) do 
xstring.CtearWriter [@writers[i]]; 

" Decide the type of column we have (passed in as Column info to 

FiieContainerSource.Create) and call proper format proc to format attribute(s) 
into a string ~ 
WITH coiumn: fs.columns[i] select from 
attribute ■ > { 

attr «-AttrjbuteFrom Attr ibuteRecord [ 

attributes, coiumn.attr]; 
coiumn.formatProc [ci, attr, ©writersfi]];}; 
extended Attribute « > { 

attr <~ ExtendedAttributeFromAttributeRecord [ 

attributes, coiumn.extendedAttr]; 
coiumn.formatProc [ci, attr, @writers[ij];}; 
multiple Attributes « > 

coiumn.formatProc [ci, attributes, @writers[i]]; 
endcase; 

ENOLOOP; 

itemOataf <-[id: attributes.fiieiD,type: attributes.type]; 

FOR i: CARDINAL IN [0..writers.length) do 

readers[i] ^-(xstring.ReaderFromWriter [@writers[i]])t ; 
endloop; 

addData ^ [ 

clientOata: itemData, 
clientDataCount: siZE[ltemFileOata], 
ctientStrings: DESCRiPTOR[readers]]; 

RETURN[addData]; 
end; 
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16.1 Overview 

The Container interfaces (ContainerSource, ContainerWindow, FileContainerSource, 
FileContainerSheil, and ContainerCache) provide the services needed to implement an 

application that appears as an ordered list of items to be manipulated by the user. 
ViewPoint Folders are a typical example of such an application. ContainerWindow 
provides the user interface for containers. It displays each item as a list of strings and 
handles selection highlighting, scrolling, and so forth. When a ContainerWindow is 
created, a record of procedures is passed in. ContainerWindow obtains the strings of each 
item by calling one of these procedures. ContainerWindow also performs user operations 
on items— such as open, props, delete, insert, take the current selection, and selection 
conversion by calling other procedures in the record. This record of procedures and their 
implementation is called a container source. A container source can be thought of as a 
supply (source) of items for a ContainerWindow. A container source is responsible for 
implementing container source operations on its underlying representation of the items in 
the source. 

The ContainerSource interface contains the procedure types that make up the record of 
procedures a container source must implement. These procedure definitions encompass all 
the operations that a source of items must be able to perform. ContainerSource also 
provides a place to save data specific to a particular container source. 

The procedure types defined by ContainerSource fall into two categories. ActOnProc, 
CanYouTakeProc, GetLengthProc, and TakeProc are operations on the source as a whole. 
ConvertltemProc, OeleteltemsProc, ItemGenericProc, and StringOfltemProc are 
operations on the individual items within the source. 

Note that the items in a container must exhibit behavior similar to the behavior defined 
by the Containee interface, such as open, props, take selection, convert. However, also 
note that the Containee interface defines the behavior of NSFiles, whereas 
ContainerSource is totally independent of NSFile. The items in a container may be backed 
by anything. The FileContainerSource interface is an example of a container source that is 
backed by NSFiles. The ViewPoint Directory application contains examples of container 
sources that are backed by Clearinghouse entries (such as the Filing and Printing 
dividers) and by simple strings in virtual memory (such as a domain divider). 
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The ContainerCache interface provides a mechanism for caching the strings and item- 
specific data for the items in a container source. The implementor of a container source 
may Hnd ContainerCache to be handy. 

16.2 Interface Items 



16.2.1 Handle, Procedures, and ProceduresObject 

Handle: type = long pointer to Procedures; 

Procedures: type = long pointer to ProceduresObject; 

ProceduresObject: type = record [ 
actOn: ActOnProc, 
canYouTake: CanYouTakeProc, 
coiumnCount: ColumnCountProc, 
convertltem: ConvertltemProc, 
deleteltems: DeleteltemsProc, 
getLength: GetLengthProc, 
itemGeneric: ItemGenericProc, 
stringOfltem: StringOfltemProc, 
take: TakeProc]; 

Handle identifies a particular container source. Handle is a pointer to a pointer 
(Procedures) to a record of procedures (ProceduresObject) that the container source 
implements. A container source typically exports a Create procedure that returns a 
Handle. This Handle is then passed to Containerwindow. Create. Whenever 
ContainerWindow needs the container source to do something, it calls the appropriate 
procedure in the ProceduresObject by using Handle | t and passing in the Handle. Note: 
Every procedure in the ProceduresObject takes a Handle as its first parameter. Fine Point: 
Actually, ContainerWindow calls the INLINE procedures described in the INLINE section, which in turn call the 
procedures in the ProceduresObject. 

Handle is a pointer to a pointer (rather than just a pointer to the ProceduresObject) to 
allow a container source to save data specific to the source. For example, a file-backed 
source needs to keep a pointer to the file. See the section on Usage/Examples for an 
explanation of how this is done. 



16.2.2 Procedures That Operate on Individual Items 
Itemlndex: type = cardinal; 
nullltem: Itemlndex s Itemlndex.LAST; 

All the procedures that operate on individual items take a Handle and an Itemlndex. An 
Itemlndex is simply a cardinal that uniquely identifies an item in the source. Note: A 
container source is an ordered list of items. An Itemlndex of "n" indicates the "nth" item in 
the source. An itemlndex of zero corresponds to the first source item. An Itemlndex should 
be thought of as a loose binding: the index of a particular item may change as a result of 
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changes to the source. For example, if an item is deleted, all the items below it are 
renumbered, nuilltem is a constant used to represent no item or unknown item. 

StringOfltemProc: type « procedure [ 
source: Handle, 
itemindex: Itemlndex, 
stringlndex: cardinal] 
RETURNS [xstring.ReaderBody]; 

The source's StringOfltemProc should return the string stringlndex of item itemindex in 
source. Each item's display is composed of strings, one for each column of the container 
window. For example, an open Folder shows four columns: the icon picture, the name, the 
size, and the date, stringlndex will be IN [0.. source. columnCountf]) (see also 
ColumnCountProc in the next section). If there is no such item (if itemindex is greater 
than the number of items in the source, for example), StringOfltemProc should raise 
Error[noSuchltem]. StringOfltemProc is used extensively, and its implementation should 
be efficient. 

ItemGenericProc: type = procedure [ 
source: Handle, 
itemindex: Itemindex, 
atom: Atom. A TOM, 
changeProc: ChangeProc ♦-nil, 
changeProcData: LONG POINTER 4- nil] 
returns [long unspecified] ; 



The source's ItemGenericProc is invoked to perform an operation on one of the items in the 
container, itemindex indicates which item to operate on. The operation is specified by 
atom. Some of the typical atoms are: Open, Props, CanYouTakeSelection, TakeSelection, 
TakeSelectionCopy. This procedure is just like the genericProc that a 
Containee.lmplementation must provide. (See the Containee interface for a complete 
description of the atoms and their return values.) changeProc must be called if the 
ItemGenericProc causes the source to change. changeProc and changeProcData are 
described in more detail below in the section on changeProc types. 

ConvertltemProc: type = procedure ( 
source: Handle, 
itemindex: Itemindex, 

n: CARDINAL 4-1, 

target: Seiection.Target, 

zone: uncounted zone, 

info: Seiection.Con version! nfo [convert[]] , 

changeProc: ChangeProc *- nil, 

changeProcData: long pointer*- nil] 

RETURNS [value: Selection. Value); 

The source's ConvertltemProc is invoked to convert one or more of the items in source, 
just as if the item was the current selection and Selection. Convert had been called, 
itemindex indicates the first item to convert, n indicates how many consecutive items to 
convert, target, zone, info, and value are all identical to the parameters for 
Selection.ConvertProc (see the Selection interface). If n>l, then info is the enumeration 
variant; otherwise, it is the convert variant. changeProc must be called if the 



l(v3 



16 



ContainerSource 



ConvertltemProc causes the source to change—for example, when an item is moved out of 
the source. changeProc and changeProcOata are described in more detail in the section on 
changeProc types. 

DeleteltemsProc: type s procedure [ 
source: Handle, 
itemlndex: Itemlndex, 
n: CARDINAL ♦-I, 
changeProc: ChangeProc <- nil, 
changeProcOata : lom pointer «- nil] ; 

The source's DeleteltemsProc is invoked to delete consecutive items from source, 
itemlndex is the first item to delete, n is the number of items to delete. changeProc must 
be called if the DeleteltemsProc causes the source to change, that is, if the deletion is 
successful. changeProc and changeProcData are described in more detail in the section on 
changeProc types. 

16.2.3 Procedures That Operate on the Entire Source 

ColumnCountProc: type » procedure [ source: Handle] returns [columns: cardinal]; 

The source's ColumnCountProc should return the number of columns in source, that is, 

the number of strings in each item. Fine point: typically, the number of columns is the same as COUNT 
[ContainerWindow.CoiumnHeaders]. 

GetLengthProc: type = procedure [ source: Handle] 

returns [length: cardinal, totalOrPartial: TotalOrPartial «- total]; 

TotalOrPartial: TYPE = {total, partial}; 

The source's GetLengthProc should return the total number of items currently in the 
source. This operation is performed often and should be efficient. Some container sources 
have indeterminate length until after an initial enumeration has completed (for example, 
clearinghouse enumerations). These sources may return [totalOrPartial: partial] while the 
initial enumeration is in progress. This lets the ContainerWindow display mechanism 
know that there are more items coming, while giving it some information along the way. 
Once a source knows how many items are in the source (or for those sources that know 
right from the start how many items are in the source (such as NSFile-backed sources), the 
GetLengthProc should return [totalOrPartial.: total].) 

ActOnProc: type s procedure [ source: Handle, action: Action]; 

Action: type = {destroy, reList, sleep, wakeup}; 

The source's ActOnProc is invoked to request some action of the source. Action indicates 
what the source should or can do. 

destroy The term destroy means that the source should destroy itself, freeing 

all storage and releasing all resources associated with the container 
source instance. 
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sleep The term sleep means that the source should release whatever 

resources it can without losing information; it is a hint that the 
container source will not be used for awhile. 

wakeup The term wakeup means that the source is going to be used and should 

resume its normal state, undoing whatever was done for sleep. 

relist The term relist means that the source should reenumerate itself 

because its backing store has been changed. 



CanYouTakeProc: type s procedure [ 
source: Handle, 

selection: Seiection.ConvertProc «-nil] 
RETURNS [yes: boolean]; 



The source's CanYouTakeProc is involved to determine if the container source can take the 
selection. If selection is nil, the current selection should be used (call Selection.Convert). 
Otherwise the Seiection.ConvertProc is used to obtain an arbitrary selection. If the 
CanYouTakeProc returns yes = true, then the source's TakeProc may be called. Fine point: 
The Selection interface does not support passing in an arbitrary ConvertProc. It is the responsibilty of clients 
that pass in arbitrary selections to make sure the source can properly handle this case. This routine is 
intended to provide an efficient check on the compatibility of the objects being copied or 
moved. The common use of this routine is to provide feedback to the user. If a 
CanYouTakeProc returns true, the client may choose to highlight the target. This is 
normally at the level of a file-type check. More elaborate checking is not necessary; for 
example, a file-backed container source would not check the source for protection or 
uniqueness violations. These should be handled by the TakeProc. 



TakeProc: type = procedure [ 
source: Handle, 

copyOrMove: Seiection.CopyOrMove, 
afterHint: Itemlndex nullltem, 
withinSameSource: boolean <- false, 
changeProc: ChangeProc «-nil, 
changeProcOata: long pointer*- nil, 
selection: Seiection.ConvertProc <- nil] 
returns [ok: boolean]; 

beforeltemZero: Itemlndex ■ itemlndex.LAST- 1; 



The source's TakeProc is invoked to add items to the container source. copyOrMove tells 
the source whether to do a move or a copy of the selection. afterHint indicates the item the 
new item should be inserted after. Fine point: This is only a hint to the container source, because the 
ultimate position of the new item may depend on a sort order built in to the source. afterHint defaults to 
nullltem, which indicates that the caller doesn't care where the new item goes. If afterHint 
a beforeltemZero, the source should insert the new item before the first item. 
changeProc must be called if the TakeProc causes the source to change. 
withinSameSource » true indicates to the source that the item(s) being moved or copied 
into the source are also in that same source—such as when the user moves or copies 
something from one place in a container to another place in the same container. This case 
usually involves some special case processing by the source (especially for move). 
changeProc and changeProcData are described in more detail in the next section. 
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selection indicates the objects to be moved or copied. If selection is nil, the current _ 
selection should be used (call Selection.Convert.) Otherwise the Seiection.ConvertProc is used ■ 
to obtain an arbitrary selection. Fine point: Refer to the CanYouTakeProc description for further 
discussionof arbitrary selections, ok indicates whether the TakeProc was successful or not. This 
routine is usually preceded by a call to the source's CanYouTakeProc. 

16.2.4 ChangeProc Types 

A source's ConvertProc, OeleteitemsProc, ItemGenericProc, and TakeProc all take a 
ChangeProc as an input parameter. This ChangeProc must be called by the source 
whenever any item or items in the source changes. This allows the ContainerWindow 
display code to keep the display up to date with the source. For example, a call to the 
source's ItemGenericProc with an atom of Props causes a property sheet to be displayed for 
an item. If the user then edits, for example, the name of the item, and closes the property 
sheet, the source must detect this change, update its backing, and call the ChangeProc 
that was passed into the ItemGenericProc. This ChangeProc (supplied by 
ContainerWindow) then causes the changed item(s) to be redisplayed. 

ChangeProc: type = procedure [ 
changeProcOata: long pointer, 
cliangelnfo: Changelnfo ]; 

A ChangeProc and changeProcData are passed to a source's ConvertProc, 
OeleteitemsProc, ItemGenericProc, and TakeProc . Because the changeProcData had to be 

allocated from someplace, the changeProc must always be called, even if there were no 
changes to the source. The source must call the ChangeProc with the changeProcData and 
any changelnfo. 

Changelnfo: type = record [ 

var: select changeType: ChangeType from 
replace ■ > [item: Itemlndex], 

insert > > [insertinfo: long descriptor for array of Editlnfo], 
delete « > [deleteinfo: EditlnfoL 
all, noChanges « > null, 
endcase ]; 

ChangeType: type * { replace, insert, delete, all, noChanges}; 

Changelnfo is passed to the ChangeProc to tell the display code exactly what changed. A 
container source can be smart and pass specific Changelnfo (for example, "3 items were 
inserted after item 4 and 2 items were inserted after item 6" may be constructed with the 
insert variant) or be dumb and simply pass the all variant, which causes a total repaint of 
the container display, replace indicates that a single item has changed, insert indicates 
that one or more items have been inserted, delete indicates that one or more items have 
been deleted, all indicates that the entire source has been changed. 
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Editlnfo: type = record [ 
afterltem: Itemlndex, 
nitems: cardinal]; 

Editlnfo is used with the insert and delete variants of Changelnfo to indicate how many 
items have been inserted or deleted and where they were inserted at or deleted from. 



16.2.5 Errors 



A container source may raise Error or Signal as appropriate. 

Error: error [code: ErrorCode, msg: XString. Reader nil, 
error: error nil, errorData: long pointer to unspecified <~ nil]; 



Signal: signal [code: ErrorCode, msg: XStri ng. Reader <- nil. 
error: error <- nil, errorData: long pointer to unspecified nil]; 



A source's ItemGenericProc (and ConvertltemProc and DeleteltemsProc) should never 
assume that it has been called by a ContainerWindow and therefore should never call 
such facilities as Attention.Post or UserTerminal.BlinkDisplay. (The application might be 
called by CUSP, for example.) Rather, the source should raise ContainerSource. Error or 
Signal with an appropriate message. The caller of the source's ItemGenericProc should 
catch these errors and do the appropriate thing. In the typical case, the ContainerWindow 
calls the source's ItemGenericProc, catches the error, and calls Attention.Post with the 
passed message. CUSP could catch the error and log the message in a log file, msg is the 
message to display to the user, error is the actual lower-level error that occurred that 
caused Error or Signal to be raised. errorData points to any additional data that 
accompanied the lower level error. 

ErrorCode: type = machine dependent {invalidParameters(O), accessError, fileError, 
noSuchltem, other, last(1 5)}; 

invalidParameters indicates that some parameters were invalid; for example, the 

source was not the correct type (the Procedures did not match). 

accessError indicates an attempt to perform an operation that violates the 

created access option (for sources that implement access 
controls). 



fiieError indicates a file system error (for sources that are backed by 

files). 

noSuchltem A container source implementation should raise 

Error[noSuchltem] if one of the container source's procedures is 
called with an Itemlndex for an item that is not in the source. 



other may be raised to indicate any other problem. 

Fine point: Error and Signal are EXPORTed by the FiieContainerSource implementation because ContainerSource 

has no implementation. 
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16.2.6 INLINES 

The following INLINE procedures are provided as a convenience to clients that wish to use 
object notation when calling a container source. ContainerWindow is the only typical 
client of these procedures. 

ActOn: ActOnProc = inline {...}; 
CanYouTake: CanYouTakeProc s inline {...}; 
CoiumnCount: ColumnCountProc = inline {...}; 
Convertltem: ConvertltemProc = inline {...}; 
Deleteltems: DeieteltemsProc = inline {...}; 
GetLength: GetLengthProc » inline {...}; 
ItemGeneric: ItemGenericProc = inline {...}; 
StringOfltem: StringOfltemProc = inline {...}; 
Take: TakeProc = inline {...}; 

16.3 Usage/Examples 

The reason that Handle is a pointer to a pointer (rather than just a pointer to the 
ProceduresObject) is to allow a container source to save data specific to the source. For 
example, a file-backed source needs to keep a pointer to the file. This is done in the 
following example. 

16.3.1 ContainerSource Example 

1. Declare a ContainerSource.ProceduresObject in the global frame of the module and fill it 
with the appropriate procedures. 

mySourceProcs: ContainerSource.ProceduresObject <~ [ 
actOn: MyActOn, 
canYouTake: CanlTake, 
columnCount: MyCofumnCount, 
convertltem: ConvertMyltem. 
deleteltems: DeleteMyltems, 
getLength: GetMyLength, 
itemGeneric: MyltemGeneric, 
StringOfltem: StringOfMyltem, 
take: MyTake]; 

2. Declare a record that has a ContainerSource. Procedures (Procedures, not 
ProceduresObject!) as its first field and initialize this field to point to the 
ProceduresObject declared in the global frame. The rest of the record should contain 
whatever data the source needs to perform all the operations it will be requested to 
perform. Also declare a pointer to this record. 

MySource: type = long pointer to MySourceObject; 

MySourceObject: type a record [ 

procs: ContainerSource.Procedures «~ ©mySourceProcs, 
otherStuff : . . . J; 
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3. When creating the source, allocate the MySourceObject record and fill it with any 
relevant data. Return a pointer to the Procedures field of the record (@ms.procs 
below). Note: This return value is a pointer to a ContainerSource.Procedures, which is a 
ContainerSource.Handle. 

Create: public procedure [otherStuff : . . . ] returns [source: ContainerSource.Handie] ■ { 
ms: MySource z.new [MySourceObject [otherStuff: otherStuff]]; 
RETURN[@ms.procs]; 

}; 

4. Every procedure in the FroceduresObject should first loophole the 
ContainerSource.Handle that was passed in into a pointer (MySource) to the source's data 
record (MySourceObject). After the loophole, the fields of the source's data record, 
such as ms.otherStuff, can be directly accessed. This works because the first field in 
the source's data record is a Procedures. Note that the loophole is performed in a 
procedure that also checks to be sure that the Procedures field of the passed source 
points to this source's procedures (if source f # (^mySourceProcs then). . 

ActOnFile: ContainerSource.ActOnProc a { 
ms: MySource « ValidMySource[source]; 

. . . ms.otherStuff. . . 

}; 

'^^z VaiidMySource: procedure [source: ContainerSource.Handle] RETURNS [ms: MySource] > { 

IF source ■ nil then ContainerSource.Error [invalidParameters] ; 
IF source | # @mySourceProcs then ContainerSource.Error[invalidParameters]; 

}; 



16.3.2 Errors and Signals 

For example, this client catches an NSFiie.Error and raises Containee. Error, passing along the 
ERROR and the NSFile.ErrorRecord: 

message: xstring.ReaderBody; 
errorRecord: NSFile.ErrorRecord; 
signal: -GENERIC- signals- nil; 
file<-NSFiie.OpenByReference [reference: ... ! 
NSFiie.Error ■ > { 
errorRecord <- error; 
signal <-LOOPHOLE[NSFiie.Error, signal]; 
GOTOErrorExIt}]; 
Operate on the file.- 
NSFiie.Close[file]; 
exits 

ErrorExit ■ > { 

message <h- xstring.FromSTRING["NSFiie.Error"L]; 
ContainerSource.Error [ 
code: fileError, msg: ©message, error: signal, errorOata: ©errorRecord]; 
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16.4 Index of Interface Items 



Item Page 

Action: type 4 

ActOn: ActOnProc 8 

ActOnProc: type 4 

beforeltemZero: Itemlndex 5 

CanYouTake: CanYouTakeProc 8 

CanYouTakeProc: type 5 

Changelnfo: type 6 

ChangeProc: type 6 

ChangeType: type 6 

ColumnCount: CotumnCountProc 8 

ColumnCountProc: type 4 

Convertltem: ConvertltemProc 8 

ConvertltemProc: type 3 

Deleteltems: DeleteltemsProc 8 

DeleteltemsProc: type 4 

Editlnfo: type 7 

Error: error 7 

ErrorCode: type 7 

GetLength: GetLengthProc 8 

GetLengthProc: type 4 

Handle: type 2 

ItemGeneric: ItemGenericProc 8 

ItemGenericProc: type 3 

Itemlndex: type 2 

nul litem: Itemlndex 2 

Procedures: type 2 

ProceduresObject: type 2 

Signal: signal 7 

StringOfltem: StringOfltemProc 8 

StringOfltemProc: type 3 

Take: TakeProc 8 

TakeProc: type 5 

TotalOrPartiai:TYPE 4 



ContainerWindow 



17.1 Overview 

The ContainerWindow interface supports the creation of ViewPoint-like container 
windows. A container window provides a user interface that operates on a list of objects 
that are displayed in rows. Each container window has one or more columns; all rows 
display the same number of columns. 

The ContainerWindow implementation maintains the display and manages user-invoked 
actions such as scrolling, selection, notifications, open within, show next/previous, and so 
forth. ContainerWindow takes a body window, a ContainerSource, and a specification of 
the columns and makes the window behave like a container. Note: This interface does not 
depend on NSFile: the objects represented by rows in the container do not have to be backed 
by NSFiles. 

17.2 Interface Items 

17.2.1 Create and Destroy a ContainerWindow 

Create: procedure [ 

window: window. Handle, 
source: ContainerSource. Handle, 
columnHeaders: ColumnHeaders, 
firstltem: ContainerSource.ltemlndex <-01 

RETURNS [ regularMenultems, topPusheeMenultems: MenuOata-ArrayHandle]; 

CreateX: procedure [ 

window: window.Handle, 
source: ContainerSource.Handie, 
columnHeaders: ColumnHeaders, 
firstltem: ContainerSource. Itemlndex <-0, 
access: Access <- full Access] 

RETURNS [ regularMenultems, topPusheeMenultems: MenuData.ArrayHandle]; 
ColumnHeaders: type = long descriptor for array of ColumnHeaderlnfo; 
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CoiumnHeaderlnfo: type s record [ 

width: CARDINAL, 
wrap: BOOLEAN, 

heading: xstring.ReaderBody]; 
Access: TYPE ■ packed array AccessType of BooleanFalseOefault; 
BooieanFaiseOefault: TYPE ■ boolean false ; 
AccessType: type * {open, dropOn, convert, add, delete, props}; 
fullAccess: Access ■ all[true]; 

readOnlyAccess: Access > [open: true, convert: true, props: true]; 

dividerAccess: Access « [open: TRUE,dropOn: true, convert: true, props: true]; 

Create turns an ordinary window into a container window, window must be a 
StarWindowShell body window, source supplies a source of items to be displayed and 
manipulated (see the ContainerSource and FileContainerSource interfaces). 

CreateX is just like Create, but with the additional access parameter, ContainerWindow 
displays an appropriate message if the user tries to do something for which proper access 
is not provided. CreateX is defined in ContainerWindowExtraS.mesa. 

columnHeaders describes the column widths and supplies column headings. The columns 
are displayed in the order given by this array. For each column, width is the number of 
bits the column should take, and heading is a string that is displayed at the top of the 
column, wrap indicates what to do when a string that the container window wants to 
display is wider than width. If wrap = true, the string should be wrapped around; 
otherwise, it will be truncated. Fine point: columnHeaders is copied by Create, so this structure may be in 
the client's local frame. 

firstltem indicates the item that should be displayed first when the container window is 
initially displayed. 

regularMenuitems and topPusheeMenuitems are the menu items that the container 
window needs to have in the StarWindowShell. They should be added (by the client) to the 
menu that is installed in the StarWindowShell that this container window is a part of 
(these contain menu items such as Show Next and Show Previous). 

Destroy: procedure [window: window.Handle]; 

Destroys the data associated with, the container window. Does not destroy the window 
itself. May raise Error [ notAContainerWindow ]. 

17.2.2 Item Operations 

The individual containees in a container window are referred to as items (from _ 
ContainerSource.ltemlndex) They are sequentially numbered starting with zero. 
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DeieteAndShowNextPrevious: procedure ( 
window: window. Handle, 
item: containerSource.lteml ndex, 
direction: Direction <~ next]; 

DeieteAndShowNextPrevious: procedure [ 
window: window.Handie, 
item : Conta inerSource .Ite m I ndex, 
direction: Direction <- next] 
returns [newOpenShell: starWindowSheii.Handie]; 

Direction: type s {next, previous}; 

DeieteAndShowNextPrevious deletes item from the container source and the display, and 
then displays the next or previous item. When this procedure is called, the container 
window shell is expected to be on top. In particular, the shell of the item named in the 
item parameter should have been destroyed. If this item is opened within the container 
window, the client should call StarWindowShell.Pop until the shell returned from that call is 
equal to the container window shell. The second DeieteAndShowNextPrevious is defined 
in Container WindowExtra2. mesa. It is identical to the first one but also returns the shell 
just opened. May raise Error[notAContainerWindow] or Error[noSuchltem]. 

GetOpenltem: procedure [window: window.Handie] 

RETURNS [item: ContainerSource.ltemlndex <-ContainerSource.nullltem]; 

Returns the item that is currently open within the container. If no item is open, it returns 
ContainerSource.nullltem . May raise Error[notAContainerWindow]. 

GetSelection: procedure [window: window.Handie] 
RETURNS [first, lastPlusOne: ContainerSource.ltemlndex]; 

Returns the items currently selected in the ContainerWindow. first ■ last ■ 
ContainerSource.nullltem means there is no selection. 

Selectltem: procedure [window: window.Handie, 
item: ContainerSource.ltemlndex]; 

Selects the specified item and implicitly calls MakeltemVisible. MakeltemVisible is in a 
friends-level interface. Note: MakeltemVisible forces item to be visible in window. If there 
is more than a screenful of items left following item, it is put at the top of the window. If 
less than a screenful remains, item is put at the bottom of the window with as many items 
as will fit before it. May raise Error[notAContainerWindow] or Error[noSuchltem]. 

17.2.3 Operations on a ContainerWindow 

Isit: PROCEDURE [window: window.Handie] returns [yes: boolean]; 
Returns TRUE if the window passed in is a ContainerWindow. 



GetSource: procedure [window: window.Handie] 

RETURNS [source: ContainerSource.Handle]; 
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Returns the ContalnerSource associated with this window. May raise 
Error[notAContainerWindowl. SetSource allows the client to change the source and the 
SourceModif yProc allows the client to modify the source. 

SetSource: procedure [ 

window: window.Handie, newSource: ContainerSource.Handle] 
RETURNS [oidSource: Handle]; 

SourceModifyProc: type ■ procedure [ 

window: Window.Handie, source: ContainerSource.Handle] 
RETURNS [changelnfo: Changelnfo]; 

ModifySource: procedure [window: window.Handle, proc: SourceModifyProc]; 

ModifySource calls the source modification proc from within its monitor. 

Update: procedure [window: window.Handle]; 

Called when the correspondence between the source and the display is invalid. Items in 
the display are redisplayed to reflect any changes in the source. May raise 
ErrOr[nOtAContainerWindOW]. Fine point: Clients do not normally need to call this routine unless they 
manipulate the source directly. All user-initiated operations on a ContainerWindow cause the display to be 
updated automatically. 



17.2.4 Errors 

Error: ERROR [code: ErrorCode]; 

ErrorCode: type = machine dependent {notAContainerWindow(O), noSuchltem, last(7)}; 

Any operations that operate on a container window may raise this error. 
notAContainerWindow is raised if the window passed in is not a container window (that 
is, was not passed to Create). noSuchltem may be raised if an operation specifies a non- 
existent item. 



17.3 Usage/Examples 

The following example is taken from the implementation of the FileContainerShell 
interface. It illustrates the steps involved in creating a container window: creating a 
container source, creating a StarWindowShell, creating a body window inside the shell, 
creating the container window, and finally merging the menu items returned by 
ContainerWindow.Create with its own menu commands and installing those commands in 
the shell. It also gives a sample StarWindowShell transition procedure that destroys the 
container source and the container window. 

- From FileContainerShelllmpl.mesa 

MenultemSeq: type a record [ 

SEQUENCE length: cardinal of MenuData.ltemHandle]; 

Create: public procedure [ 
file: NSFiie.Reference, 
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columnHeaders: ContainerWindow.ColumnHeaders, 

columnContents: FiieContainerSource.ColumnContents, 

regularMenultemSftopPusheeMenultems: MenuOata-ArrayHandle <- nil, 

scope: NSFiie.Scope <- []. 

position: ContainerSource.ltemlndex <-0, 

options: FiieContainerSource.Options <~ (]] 

RETURNS [shell: StarWindowShell.Handle] ■ 



BEGIN 

body: window.Handle nil; 
source: ContainerSource.Handle nil; 

cwRegularMenultems, cwTopPusheeMenultems: MenuOata-ArrayHandie; 

mergedMenultems: long pointer to MenultemSeq <-nil; 

menu: MenuOata.MenuHandle; 

name: xstring.ReaderBody; 

ticket: Containee.Ticlcet; 

data: containee.Data *- [file]; 

type: NSFiie.Type; 

smallPicture: xstnng.Character; 

IF file a NSFiie.nullReference then return [ [nil] ]; 

source FlleContainerSource.Create [ 
file: file, 

columns: columnContents, 
scope: scope, 
\tm0^ options: options]; 

[name, ticket] <- Containee.GetCachedName [@data]; 

type *- Containee.GetCachedType[@data]; 

smallPicture <~ containee.Getlmplementation[type].smallPicture; 



shell *- StarWindowSheil.Create [ 
name: @name, 
namePicture: smallPicture, 
sleeps: false, 

transltlonProc: OestroyProc]; 
Containee.ReturnTicket [ticket]; 



body <- starWindowSheii.CreateBody [sws: shell, box: [[0,0],[700, 29999]]]; 

[cwRegularMenultems, cwTopPusheeMenultems] Containerwindow.Create [ 
window: body, 
source: source, 

columnHeaders: columnHeaders, 
firstltem: position]; 



mergedMenultems ^ MergeMenuArrays [cwRegularMenultems, regularMenuitems); 
IF mergedMenultems # nil then 

BEGIN 

menu <— MenuOata.CreateMenu [ 

zone: starWindowSheii.GetZone{sheil], 
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title: NIL, 

array: DESCRiPTOR[mergeclMenultems], 

copyltemslntoMenusZone: true ]; 
starWindowSheii.SetRegularCommands [shell, menu]; ^ 
z.FREE[@mergedMenuitems]; 
end; 

mergedMenultems *- MergeMenuArrays [cwTopPusheeMenuitems, 

topPusheeMenultems]; 

menu *- MenuOata.CreateMenu [ 

zone: starWindowSheii.GetZone[shell], 

title: NIL, 

array: DESCRiPTOR[mergedMenultems], 

copyltemslntoMenusZone: false ]; 
starWindowSheii.SetTopPusheeCommands [shell, menu]; 
RETURN [shell]; 
end; 

OestroyProc: StarWindowSheil.TransitionProc = 
< <[sws: StarWindowShell.Handle, state: StarWindowShell.State]> > 
BEGIN 

IF State « dead then { 

cw: window.Handle GetContainerWindow[sws]; 
source: containerSource.Handle <-GetContainerSource[sws]; 
ContainerSource.ActOn [source, destroy]; 
ContainerWindow.Destroy[cw]; }; 

return; 
end; 

MergeMenuArrays: proc [itemArrayl, itemArray2: MenuData-ArrayHandle] 
returns [mergedSeq: long pointer to MenultemSeq] ■ 

BEGIN 

i: cardinal <-0; 

IF itemArrayl a nil and item Array2 ■ nil then return[nil]; 

mergedSeq «-z. NEW [MenultemSeq[item Array 1. LENGTH * itemArray2.LENGTH]]; 

FOR j : cardinal in (0..itemArray1 .length) do 

mergedSeq[i] *- itemArrayl [j]; 

i ^i + 1; 

endloop; 

FOR j: CARDINAL IN [0..itemArray2.LENGTH) do 

mergedSeq[i] <-itemArray2(]]; 

\*-\ + 1 ; 

endloop; 
RETURN(mergedSeq] ; 
end; 



17-6 



Viewpoint Programmer's Manual 



17 



17.4 Index of Interface Items 



Item Page 

Access: TYPE 2 

AccessType: type 2 

BooleanFalseOefault: type 2 

ColumnHeaderlnfo: type 2 

CoiumnHeaders: type 1 

Create: procedure 1 

CreateX: procedure 1 

OeleteAndShowNextPrevious: procedure 3 

Destroy: procedure 2 

Direction: type 3 

dividerAccess: Access 2 

Error: error 4 

ErrorCode: type 4 

full Access: Access 2 

GetOpenltem: procedure 3 

GetSelection:PROCEDURE 3 

GetSource: procedure 3 

ISit: procedure 3 

MakeitemVisibie: procedure 3 

ModifySource:PROCEDURE 4 

readOnlyAccess: Access 2 

Seiectltem'.PROCEDURE 3 

SetSource: PROCEDURE 4 

SourceModifyProc: PROCEDURE 4 

Update: PROCEDURE 4 
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18.1 Overview 

In performing various functions, an application may wisli to save and retrieve state from 
one notification to the next. This is an immediate consequence of the notification scheme, 
for a tool cannot keep its state in the program counter without stealing the processor after 
responding to an event. Thus the application must explicitly store its state in data. 
Because most notification calls to the application provide a window handle, it is natural to 
associate these contexts with windows. The context mechanism provides an alternative to 
the application's having to build its own associative memory to retrieve its context, given 
a window handle. 

Typically, an application obtains a unique Type for its context data by calling UniqueType 
in the startup code for the application. Whenever a window is created, the client allocates 
some context data and calls Create to associate that data with the window Whenever the 
client is called to perform some operation on the window (for example, to display the 
contents of the window or to handle a notification), it calls Find to retrieve the data saved 
with the window. Finally, when the window is being destroyed, the client (orViewPoint) 
calls Destroy, which calls the client's DestroyProcType to give the client an opportunity to 
free the data. 

18.2 Interface Items 

18.2.1 Creating/Destroying a Context 

UniqueType: procedure returns [type: Type]; 

The procedure UniqueType is called if a client needs a unique Type not already in use 
cither by VicwPoint or by another client. If no more unique types are available, the error 
Error[tooManyTypes] is raised. 

Create: procedure [ 

type: Type, data: Data, proc: DestroyProcType, window: Window.Handle]; 
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The procedure Create creates a new context of type type that contains data. The context is jgg^ 
associated with window; it is said to "hang" on the window. If window already has a 
context of the specified type, it raises the error Error[dupiicateType]. If the window is nil, 
it raises the error Error[windowlsNIL]. The proc is supplied so that when the window is 
destroyed, all of the context can be destroyed (deallocated). 

Type: type * machine dependent{ 
ail(0).first(1). lastAtlocated(37737B), last(37777B)}; 

Type is unique for each client of the context mechanism. An argument of this type is 
passed to most of the procedures in this interface so that the correct client data can be 
identified. 

Data: TYPE a LONG pointer TO UNSPECIFIED, - 

Data is the value that a client may associate with each window. It is typically a pointer to 
a record containing the client's state for some window. 

Destroy ProcType: type « procedure [Data, Window.Handie]; 

A DestroyProcType is passed to Create so that the client can be notified when the context 
should be destroyed. This may be the result of the window being destroyed. 

Destroy: procedure [type: Type, window: Window.Handie]; ^gi^ 

The procedure Destroy destroys a context of a specific type on window. If the context 
exists on the window, it calls the DestroyProcType for the context being destroyed. 

DestroyAil: procedure [window: Window.Handie]; 

The procedure DestroyAil destroys all the contexts on window. Fine point: OestroyAii can be 

very dangerous because ViewPoint keeps its window-specific data in contexts on the window. DestroyAil should 
not be used except in special circumstances. It is called by the routines that destroy windows. 

NopDestroyProc: DestroyProcType; 

The procedure NopDestroyProc does nothing. It is provided as a convenience to clients 
that do not want to create their own do-nothing DestroyProcType to pass to Create. 

SimpieDestroyProc: DestroyProcType; 

The procedure SimpieDestroyProc merely calls the system heap deallocator on the data 
field. It is provided for clients whose context data is a simple heap node in the system zone. 

18.2.2 Finding a Context on a Window 

Find: procedure [type: Type, window: Window.Handie] returns [Data]; 

The procedure Find retrieves the data field from the specified context for window, nil Is 
returned if no such context exists on the window. 
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FindOrCreate: procedure [ 

type: Type, window: Window.Handle, createProc: CreateProcType] returns [Data]; 

The procedure FindOrCreate resolves the race that exists when creating new contexts in a 
multi-process environment. If a context of type type exists on window, it returns the 
context's data; otherwise, it creates a context of type by calling createProc and then 
returns data. If the window is nil, it raises the error Error[windowisNIL]. 

CreateProcType: type * procedure returns [Data, OestroyProcType]; 

CreateProcType is used by FindOrCreate. The procedure passed in as an argument to 
FindOrCreate is called to create a context only if a context of the appropriate type cannot 
be found. 

Set: PROCEDURE [type: Type, data: Data, window: window.Handle]; 

The procedure Set changes the actual data pointer of a context. Subsequent Finds will 
return the new data. Note: The client can change the data that the data field of a context 
points to at any time. This could lead to race conditions if multiple processes are doing 
Finds for the same context and modifying the data. It is the client's responsibility to 
MONITOR the data in such cases. If the window is nil, it raises the error 
Error[windowisNIL]. 

18.2.3 Acquiring/Releasing the Context 

Acquire: procedure [type: Type, window: Window.Handle] returns [Data]; 

The procedure Acquire retrieves the data field from the specified window. It returns nil if 
no such context exists on the window. It also locks the context object so that no other calls 
on Acquire or Destroy with the same type and window will complete until the context is 
freed by a call on Release. 

Release: procedure [type: Type, window: Window.Handle]; 

The procedure Release releases the lock on the specified context object for window that 
was locked by the call on Acquire. If the specified context cannot be found or if it is not 
locked. Release is a no-op. 

18.2.4 Errors 

ErroKode: type ■ {duplicateType, windowisNIL, tooManyTypes, other}; 

dupiicateType is raised by Create if a context of the given type already exists on the 
window passed as an argument. 

windowisNIL is raised if the client has passed in a nil window. 

tooManyTypes is raised if UniqueType has been called too many times. 

Error: error [code: ErrorCode]; 

Error is the only error raised by any of the Context procedures. 
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18.3 Usage/Examples 

Acquire and Release can be used in much the same way as a Mesa monitor (See the Mesa 
Language Manual: 610E00150). It is important that the client call Release for every 
context that has been obtained by Acquire; this is not done automatically. The cost of 
doing an Acquire is barely more than entering a monitor and doing a Find. Using this 
technique allows the client to monitor its data rather than its code. 

If several tools must share global data, it is possible to place a context on 
Window. rootWindow that is never destroyed, even when the bitmap is turned off. To share 
a Type without having to export a variable, use one in the range (lastAiiocated.Jast]. 
Contact the support organization to have one allocated to you. 

18.3.1 Example 

myContextType: Context.Type «-Context.UnrqueType(]; 

MyContext: type a long pointer to MyContextObject; 

MyContextObject: type » record [...]; 

sysZ: uncounted zone Heap.systemZone; 

MakeShellAndBodyWindow: procedure « { 

myContext: MyContext *~ sysZ.NEW (MyContextObject <~ { 

- initialize fields o/ MyContextObject —] ]; 

— Note: If some field of MyContextObject were a pointer to some more allocated 
storage, then t/ie Contcxt.SimpieOestroyPfoc would not be used. A client-supplied 
DestroyProcType that freed both MyContextObject and the storage pointed to by 
MyContextObject would have to be provided. 

shell : starWindowSheii.Create [...] ; 

body: starWindowSheii.CreateBody [sws: shell, 

repaintProc: MyRepaint, 

bodyNotifyProc: My Notify]; 
Cont«xt.Create [type: myContextType, 

data: myContext, 

proc: Context. Si mpleOestroyProc, 

window: body]; 

}; 
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MyRepaint: PROCEDURE [window: window.Handle] ■ { 
myContext: MyContext <~ FindContext [window]; 

}; 

MyNotify: TiP.NotifyProc ■ { 

myContext: MyContext FindContext [window]; 

}; 

FindContext: procedure [window: window.Handle] 
RETURNS [myContext: MyContext] « { 
myContext <-context.Find [myContext Type, window]; 
IF myContext *■ nil then error; 

}; 



Context 



18.4 Index of Interface Items 



Item Page 

Acquire: procedure 3 

Create: procedure 1 

CreateProcType: type 3 

Data: type 2 

Destroy: procedure 2 

DestroyAII: PROCEDURE 2 

DestroyProcType: type 2 

Error: error 3 

ErrorCocie- type 3 

Find: procedure 2 

FindOrCreate: procedure 3 

NopOestroyProc: procedure 2 

Release: procedure 3 

Set: procedure 3 

SimpleOestroyProc: procedure 2 

Type: TYPE 2 

UniqueType: procedure 1 
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19.1 Overview 

The Cursor interface provides a procedural interface to the hardware mechanism that 
implements the cursor on the screen. This interface defines several cursor shapes as well 
as operations for client-defined cursors. Because there is a single global cursor, it should 
be manipulated only through this interface and only from the notifier process. 

The major data structure defined in this interface is the Object, which defines not only the 
array of bits that represents the picture of the cursor but also its hot spot. The hot spot of a 
cursor consists of the coordinates within the 16-by-16 array that indicate the screen 
position pointed to by the mouse. The hardware position of the cursor is always in the 
upper- left corner of the bit array. For many cursor shapes, this position is not where the 
cursor points. For example, the pointRight cursor shape is a right-pointing arrow whose 
hot spot is at the tip of the arrow. 

There can be up to 256 different cursors, limited by the size of the Type enumeration. The 
first several types are system-defined. Clients may call UniqueType to allocate an unused 
type for their own use. 

This interface is typically used to change the cursor either by calling Set to set it to one of 
the system-defined cursors or by calling Store. To restore the cursor, save it into an Object 
by calling Fetch before it is changed. 

19.2 Interface Items 

19.2.1 Major Data Structures 

Handle: type » long pointer to Object; 

Object: TYPE a record [info: Info, array: userTerminai.CursorArray]; 
Info: TYPE s RECORD (type: Type, hotX: (0..16), hotY: [0..16)]: 



19-1 



19 Cursor 



Type: TYPE a MACHINE DEPENOENT{ 

blank(O), bullseye(1), confirm(2), ftpBoxes(3), hourGlass(4), iib(5), menu(6), 
mouseRed(7), pointDown(8), pointLeft(9), pointRight(10), pointUp(1 1), 
questionMark(12), scroiiDown(13), scroliLeft(14), scroilLeftRight(15), scroiiRight(16), 
scrollUp(17), scroiiUpOown(18), textPointer(19), groundedText(20), move(21), 
copy(22), sameAs(23), adjust(24), row(25), coiumn(26), iast(377B)}; 

Object defines the type and hot spot of the cursor as well as the 16-by-16 array of bits that 
represent the cursor's picture. 

Info contains the type and the hot spot of a cursor. 

Defined: TYPE « Type{biank..column]; 

Defined is the subrange of Type that contains the system-deiined cursors. 

19.2.2 Setting the Cursor Picture 

Set: PROCEDURE [type: Defined]; 

Set sets the displayed cursor to be one of the system-defined cursors. 
Store: procedure [h: Handle]; 

Store sets the displayed cursor to the cursor described by h. 
StoreCharacter: procedure [c: xchar.Character]; 

StoreCharacter stores the system font picture of character c into the cursor. The info is set 
to [type: coiumn.sucCr hotX: 8, hotY: 8]. 

StoreNumber: procedure [n: cardinal]; 

StoreNumber sets the cursor picture to be the number n MOD 100. If n is less than 10, the 
single digit is centered in the cursor. The info is set to [type: column.succ.succ, hotX: 8, 
hotY: 81. 

19.2.3 Getting Cursor Information 

Fetch: procedure [h: Handle]; 

Fetch copies the current cursor object into the object pointed to by h. 
Getinfo: procedure returns [info: Info]; 
Getlnfo returns the hot spot and type of the current cursor. 
FetchFromType: procedure [h: Handle, type: Defined]; 

FetchFromType copies the system-defined cursor object corresponding to type into the 
object pointed to by h. 
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19.2.4 Miscellaneous Operations 

MoveintoWindow: procedure [ 

window: window.Handie, place: window.Place]; 

MoveintoWindow moves the cursor to the window-relative place in window. 

Swap: PROCEDURE [old, new: Handle]; 

Swap places the displayed cursor object in old f and Stores the new. It is equivalent to 
Fetchfold]; Storefnew]. 

19.2.3 Client-Defined Cursors 

UniqueType: procedure returns [Type]; 

UniqueType lets clients assign u unique type to their defined cursors. It returns u Type 
that is different from all predefined types and from any that have previously been 
returned by UniqueType. The value is only valid during the current boot session. 

Cursor Picture Manipulation 
Invert: procedure returns [boolean]; 

Invert inverts each bit of the cursor picture and inverts the positive/negative state of the 
picture. It returns true if the new state of the cursor is positive. 

MakeNegative: procedure; 

MakeNegative is equivalent to MakePosltive followed by Invert. It sets the 
positive/negative state of the cursor to negative. 

MakePositive: procedure; 

MakePosltive sets the positive/negative state of the cursor to positive. The state is set to 
positive whenever Set or Store is invoiced. 

19.3 Usage/Examples 

The following example shows a client setting the cursor to an hourglass while performing 
some time-consuming action. It first saves the current cursor and restores it when it is 
done, if the action did not change the cursor. If the client knew what the cursor should be, 
the cursor would not have to be saved but could be unconditionally set . 

savedCursor: Cursor.Object; 

Cursor . Fetch [@savedCu rsor] ; 

Cursor.Set[hourGtass] 

— Do action - 

*iii«p^ iFCursor.<aetlnfo[].type a hourGlassTHENCursor.Store[@savedCursor]; 
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StoreCharacter is typically used to put small pictures in the cursor by using characters 
obtained from siinpieTextFont.AddGiientOefinedCharacter. 
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19.4 Interface Item Index 



Item Page 

Defined: type 2 

Fetch: PROCEDURE 2 

FetchFromType: procedure 2 

Getlnfo: procedure 2 

Handle: type 1 

Info: TYPE 1 

Invert: procedure 3 

Movelnto Window: procedure 3 

MakeNegative: procedure 3 

MakePosltive: procedure 3 

Object: type 1 

Set: procedure 2 

Store: procedure 2 

StoreCharacter: procedure 2 

StoreNumber: procedure 2 

Swap: procedure 3 

Type: type 2 

UniqueType: procedure 3 
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20.1 Overview 

Directory allows for clients to add dividers to the directory icon. Directory maintains a 
directory divider containing three top-level dividers: the workstation divider, containing 
those objects that exist on a per- workstation basis; the user divider, containing those 
objects that exist on a per-user or per-desktop basis; and the network divider, containing 
those objects that exist in the internet. (See the Divider and CHDivider interfaces for more 
information about dividers.) 

20.1.1 Predefined Divider Structure 

Directory automatically creates a top-level divider that backs the directory icon. To this 
divider it adds the workstation divider, the user divider, and the network divider. It adds 
three entries to the workstation divider: the prototype folder, the office aids divider, and 
the local devices divider. The user divider is emptied at each logout. Clients of the user 
divider should add their entries at each logon. Directory also automatically adds the 
organization divider to the network divider and the domain divider to the organization 
divider. Clients can add entries to the domain divider (see Figure 20.1). (See the 
Prototype interface for details of how to add prototype icons to the prototype folder and the 
Divider interface for details of how to add entries to the office aids, local devices, and user 
dividers.) 

20.2 Interface Items 

20.2.1 Adding Items to a Predefined Divider 

Dividerlype: type » {top, ws, user, domain, localDevices, officeAids}; 

A parameter of type Dividerlype is passed to AddDividerEntry to specify one of the 
predefined dividers. A value of top specifies adding a new top-level divider. 

AddDividerEntry: procedure [ 
divider: DividerType, 
type: NSFiie.Type, 
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label: xstrmg. Reader, 
data: long pointer <- nil. 

convertProc: Divider.ConvertProc nil, 

genericProc: Divider. GenericProc nil]; 

AddDividerEntry adds an entry to the divider specified by divider. If divider is equal to 
top, a new top-level divider is added, type specifies the NSFile.Type of the entry. It is used to 
obtain the Contalnee.lmplementation for the entry, label is used to label the entry when it 
appears in the divider's container window. The xstring. Reader bytes are copied, data is an 
optional data pointer to be supplied in subsequent calls to the GenericProc and the 
ConvertProc. convertProc is a Divider.ConvertProc for the entry, and genericProc is a 
oivider.GenericProc for the entry. (See the Divider interface for details.) Fine point: The 
predefined dividers are actually implemented by using the Divider interface. AddDividerEntry is actually the 
same as Divider .AddEntry, with the handle arguement replaced by a oir«ctory.OividerType. 

20.2.2 GetDividerHandle 

GetOividerHandie: procedure [divider: OividerType] returns [handle: oivider.Handie]; 

GetDividerHandle returns the Divider. handle for the predefined divider specified by 
divider. Clients can use this handle to manipulate the predefined divider with the Divider 
interface. (See the Divider chapter for more information.) 

20.3 Usage/Examples 

See the Divider and CHDivider interfaces for examples of how to add entries to the 
directory. The Divider interface also shows the implementation of AddDividerEntry. 
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Figure 20.1 Predefined Divider Structure 
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20.4 Index of Interface Items 

Item Page 

AddOividerEntry: procedure 1 

GetDividerHandle: procedure 2 

OividerType: type 1 
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21.1 Overview 

The Display interface provides elementary routines for painting into windows on the 
display screen. Procedures are provided for painting points; lines; bitmaps; repeating 
patterns; boxes filled with black, gray, white, or small patterns; circles; circular arcs; 
ellipses; conies; as well as for painting a brush as it moves along an arbitrary trajectory. 
Another procedure allows shifting the current content of a window. Procedures for 
painting text are available in the SimpleTextOisplay interface. 

The Window interface supplies facilities for managing windows. The introduction section 
of the Window chapter describes the window coordinate system and the process of 
painting into a window. The reader should be familiar with that material. 

As described in the Window chapter, the display background color, which is represented 
by a pixel value of zero, is commonly called white, and a value of one, called black. Note 
however, that the display hardware can also render the picture using zero for black and 
one for white. Clearing or erasing an area of the screen means setting all of its pixels to 
zero, or white. 

The Display interface currently contains procedures that apply to text-namely Block, 
MeasureBlock, ResolveBlock, Character, Text, and Textlnline. They are not supported. The 
SimpleTextDispiay interface provides text painting operations. 

As described in the Window chapter, the standard way for a client to paint into its window 
is to update its data structures, invalidate the portion of its window that needs to be 
painted, and then call a window. Validate routine. Window responds by calling back into 
the client's display procedure to do the painting. Nonstandard ways of painting are 
discussed in the Usage/Examples section of this chapter. 

21.2 Interface Items 

21.2.1 Painting Filled Boxes, Horizontal Lines, and Vertical Lines 
Handle: type » window.Handle; 
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Black: procedure [window: window.Handle, box: window.Box]; 
Invert: procedure [window: window.Handle, box: window.Box]; 
White: procedure [window: window.Handle, box: window.Box]; 

Black and White paint black and white boxes. Invert changes all black pixels to white and 
all white pixels to black in the box. These procedures perform their operation on the 
specified box in window. Horizontal and vertical black lines can be painted by using Black 
with a box that is one pixel wide or tall. 

Dispiay.Handle is provided for backward compatibility. 

21.2.2 Painting Bitmaps and Gray Bricks 

The procedures in this section allow the client to paint bitmaps and gray bricks into a 
window. Bitmaps and gray bricks are described in the Mesa Processor Principles of 
Operation. 

The first items below define some convenience types and constants that are used with 
bitmaps and painting. 

BitAddress: type ■ Environment-BitAddress; 

OstFunc: type ■ BitBit.OstFunc; ^•in 
BitBltFlags: type « sitBit.BitBltFlags; 

A BitBlt. BitBltFlags is an argument of the Bitmap and Trajectory operations. These flags 
control how source pixels and existing display pixels are combined to produce the final 
display pixels. The flag constants defined below cover most of the common cases. 
BitBlt. BitBltFlags are described in detail in the Mesa Processor Principles of Operation. 

replaceFiags: BitBltFlags ■ [ 

direction: forward, disjoint: true, disjointltems: true, gray: false, 
srcFunc: nuil,dstFunc: null, reserved: 0]; 

replaceFiags paints opaque black and opaque white from a bitmap. Source pixels from the 
bitmap overwrite the previous display pixels. 

textFlags, paintFlags: BitBltFlags « [ 

direction: forward, disjoint: true, disjointltems: false, gray: false, 
srcFunc: null, dstFunc: or, reserved: 0]; 

textFlags and its synonym paintFlags paint opaque black and transparent white from a 
bitmap source. Black source pixels cause black display pixels. White source pixels leave 
display pixels unchanged. 

xorFlags: BitBltFlags ■ [ 

direction: forward, disjoint: true, disjointltems: false, gray: false, ^""^ 
srcFunc: null, dstFunc: xor. reserved: 0]; 
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xorFlags is used with a source bitmap to selectively video invert existing display pixels. 
Video inverting is the process of changing white to black and black to white. Black source 
pixels invert the existing display pixels. White source pixels leave display pixels 
unchanged. 

paintGrayFlags, bitFlags: BitBltFlags ■ [ 

direction: forward, disjoint: true, disjointitems: true, gray: true, 
srcFunc: nuli,dstFunc: or, reserved: 0]; 

paintGray Flags paints opaque black and transparent white from a gray brick source. 
Black source pixels cause black display pixels. White source pixels leave display pixels 
unchanged. 

repiaceGray Flags, boxFlags: BitBltFlags ■ [ 

direction: forward, disjoint: true, disjointitems: true, gray: true, 
srcFunc: null, dstFunc: null, reserved: 0]; 

repiaceGray Flags paints opaque black and opaque white from a gray brick source. Source 
pixels overwrite the previous display pixels. 

xorGray Flags, xorBoxFlags: BitBltFlags « [ 

direction: forward, disjoint: true, disjointitems: true, gray: true, 
srcFunc: null, dstFunc: xor, reserved: 0]; 

xorGrayFtags is used with a source gray brick to selectively video invert existing display 
pixels. Black source pixels invert the existing display pixels. White source pixels leave 
display pixels unchanged. 

eraseFlags: BitBltFlags « [ 

direction: forward, disjoint: FALSE, disjointitems: FALSE, gray: FALSE, 
srcFunc: complement, dstFunc: and, reserved: 0]; 

eraseFlags erases objects. Previous display pixels are overwritten. 

Bitmap: procedure [ 

window: window.Handle, box: window.Box, address: Environment.BitAddress, 
bitmapBitWidth: cardinal, flags: BitBit.BitBitFlags paintFlags]; 

Bitmap paints the bitmap described by address and bitmapBitWidth into box in window, 
using flags to control the interaction with pixels already being displayed. Bitmap may be 
used to display a gray pattern that is not aligned relative to the window origin, 
box.dims.w must be less than or equal to bitmapBitWidth; this is not checked, flags. gray 
is ignored. 

BitAddressFromPlace: procedure [ 

base: Environment.BitAddress, x, y: natural, raster: cardinal] 
returns [Environment-BitAddress]; 

BitAddressFromPlace returns the Environment.BitAddress of the pixel at coordinates x and y 
in the bitmap described by base, raster is the number of pixels per line in the bitmap. This 
procedure is useful for calculating the address parameter of Bitmap. 
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Brick: TYPE » long descriptor for array of cardinal; 

Bricks are used by Gray and Trajectory to describe a repeating pattern to fill an area. The 
maximum size of a Brick is 16 words; each word is one row of the pattern. 

fiftyPercent: Brick; 

f iftyPercent is a brick containing a 50% gray pattern. 
Gray: procedure [ 

window: window.Handle, box: window.Box, gray: Brick <~ fiftyPercent, 
dstFunc: BitBit.DstFunc null]; 

Gray uses the source gray brick to completely fill box in window. If the content of the 
brick to be displayed is not aligned with the window origin, use Bitmap instead. The table 
below describes the effect of dstFunc. 

dstFunc resulting display pixels 

null Source pixels overwrite display pixels. 

or Black source pixels cause black display pixels. White source pixels leave 

display pixels unchanged. 

xor Black source pixels cause the existing display pixels to be inverted. White 
source pixels leave display pixels unchanged. 

and Black source pixels cause black display pixels wherever the display pixels are 
already black. All other display pixels will be made white. 

21.2.3 Painting Points, Slanted Lines, and Curved Lines 

The procedures below paint points, oblique straight lines, and circular arcs and conies. 

Point: PROCEDURE [window: window.Handle, point: window.Place]; 

Point makes the single pixel at point in window black. 

LineStyie: TYPE ■ long pointer to Li neStyleObject; 

LineStyleObject: TYPE ■ RECORD [ 

widths: array [O..DashCnt) of cardinal, 
thickness: cardinal]; 

OashCnt: cardinal • 6; 

LineStyie describes the style of lines for the Line, Circle, Ellipse, Arc, and Conic operations, 
thickness defines the width of the line in pixels, widths defines the dash structure. Each 
pair of elements is the number of pi.xels of black followed by the number of pixels of white. 
For example (widths: [4,2,0,0,0,0], thickness: 2] defines the style for a dashed line two 
pixels thick, where the dashes are four pixels on and two off. 
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Line: procedure [ 

window: window.Handle, start, stop: window.Placep lineStyle: LineStyle <~niu 
bounds: window.BoxHandle <-nil]; 

Line paints a line from start to stop in window. If bounds # nil, the line is clipped to the 
box bounds. If lineStyle is defaulted, the line is solid and is a single pixel wide. 

Circle: procedure [ 

window: window.Handle, place: window.Place, radius: integer, 
lineStyle: LineStyle <-nil, bounds: Window.BoxHandle nil]; 

Circle paints a circle centered at place in window, with the given radius. If bounds # nil, 
the circle is clipped to the box bounds. If lineStyle is defaulted, the circle is solid and is a 
single pixel wide. 

Ellipse: procedure I 

window: window.Handle, center: window.Place, xRadius, yRadius: integer, 
lineStyle: LineStyle 4~nil, bounds: window.BoxHandle <- nil]; 

Ellipse paints an ellipse with axes centered at center with an x radius of xRadius and a y 
radius of yRadius in window. The axes of the ellipse are parallel to the x-y coordinate 
system. Ellipses with oblique axes may be displayed by using Conic. If bounds # nil, the 
ellipse is clipped to the box bounds. If lineStyle is defaulted, the ellipse is solid and is a 
single pixel wide. 

Arc: PROCEDURE [ 

window: window.Handle, place: window.Place, radius: integer, 
startSector, stopSector: cardinal, start, stop: window.Place, 
lineStyle: LineStyle 4>nil, bounds: window.BoxHandle <- nil]; 

Arc paints a portion of a circular arc centered at place in window, with the given radius. 
The arc goes from the angle defined by start in the startSector to stop in the stopSector. 
Sectors are simply octants numbered from 1 to 8, with northeast being 1 and increasing 
clockwise. If bounds # nil, the arc is clipped to the box bounds. If lineStyle is defaulted, 
the arc is solid and is a single pixel wide. 

Conic: procedure ( 

window: window.Handle, a, b, c, d, e, errorTerm: long integer, 
start, stop, errorRef : window.Place, 

sharpCornered, unboundedStart, unboundedStop: boolean, 
lineStyle: LineStyle nil, bounds: window.BoxHandle nil]; 

Conic paints the portion of the curve of the equation ax2 +• by2 + cxy -t-dx + ey + /" = 0 in 
window from start to stop. Instead of passing in the last coefficient f, this procedure takes 
the errorTerm resulting from substituting start into the equation. If the conic contains 
points whose radius of curvature is less than or equal to two pixels, it must be displayed by 
using multiple calls with sharpCornered set to true; otherwise .sharpCornered should be 
FALSE. These "sharp-cornered" conies must be broken up into segments where the corners 
become a new segment's start and stop points. For example, a very long skinny ellipse 
must be displayed in two pieces. errorRef, unboundedStart, and unboundedStop are 
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ignored. If bounds # nil, the conic is clipped to the box bounds. If iineStyle is defaulted, 
the conic is solid and is a single pixel wide. 



21.2.4 Painting Parallelograms and Trapezoids 

These types and procedures are used to paint parallelograms and trapezoids: 
FixdPtNum: TYPE ■ machine dependent record [ 

SELECT OVERLAID * FROM 

wholeThing a > [li: long integer], 
parts m > [frac: cardinal, int: integer], 
endcase]; 

A FixdPtNum is a fixed-point integer with 16 bits of fraction and 16 bits of integer part. 
These numbers can be added and subtracted in a straightforward manner, while division 
and multiplication are more difficult. By using the overlaid record, the fraction and 
integer part may be obtained without shifting or dividing. FixdPtNum can e.xpress all 
practical slopes with only small errors. 

interpolator: type » record [ 
val, dVai: FixdPtNum]; 

Interpoiator is used to define parallelograms and trapezoids. The dVal term is the 
derivative with respect to y; for example, x.dVai is dx/dy. 

BiackParallelogram: proc[ 

window: Handle, p: Parallelogram, dstFunc: DstFunc null]; 

Parallelogram: type ■ record! 

' x: Interpolator, y: integer, upper left 
w: NATURAL, — across top, must be positive 
h: natural]; 

BiackParallelogram paints the parallelogram defined by p in window. dstFunc acts as in 
the procedure Gray. The parallelogram is defined as below with the slope of the 
parallelogram being p.x.dVal. In Figure 21.1 the slope is two fifths. BiackParallelogram 




Figure 21.1 Parallelogram definition 



optimizes a common case (such as diagonal lines) and runs about twice as fast as 
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GrayTrapezoid by avoiding tlie second interpolation, the noninteger width, and the gray 
alignment calulations: 

GrayTrapezoid: proc [ 

window: Handiest: Trapezoid, gray: Brick flftyPercent, dstFunc: DstFunc *- nuil]; 

Trapezoid: TYPE ■ record [ 

x: Interpolator, y: integer, upper left 

w: Interpolator, across top; must be positive 

h: natural]; 

GrayTrapezoid paints the trapezoid defined by t in window, gray and dstFunc act as in the 
procedure Gray. The trapezoid is defined in Figure 21.2 with the slope of the left side of the 
trapezoid being t.x.dVai and the slope of the right side of the trapezoid being t.x.dVai 
minus t.w.dVal. In Figure 21 2, t.x.dVai is minus one half and t.w.dVal is nine tenths. 




Figure 21.2 Trapezoid definition 



21.2.5 Painting Along Trajectories, Shifting Window Contents 

Shift: PROCEDURE [window: window.Handle, box: window.Box, newPlace: window. PI ace]; 

Shift does a block move of a rectangular portion of window's current content. This 
operation does not invoke any client display procedures, box describes the region of 
window to be moved to newPlace. If Display does not have the pixels for a visible area of 
the destination box, that area is filled with trash and marked invalid. The client should 
validate the window when it has finished altering the window content. Shift does not 
invalidate the areas vacated by the move; if they are repainted, the client should 
invalidate them. If Shift is executed from within a display procedure, it does not clip the 
region painted to window's invalid area list. Invalid area lists are explained in the 
Window chapter. 
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Trajectory : public procedure [ 

window: window.Handle, box: window.Box <~window.nullBox, proc: TrajectoryProc, 
source: long pointer <- nil, bpl: cardinal 4-16, height: cardinal 4-16, 
flags: BitBit.BitBitFtags 4- bitFtags, mIssesChiidren: boolean 4- false, 
brick: Bricic4-NiL]; 

TrajectoryProc: type • procedure [Handle] returns [window.Box, integer] ; 

Trajectory repeatedly calls proc and paints a brush where proc specifies. The brush may 
be either a gray brick or a portion of the bitmap source. Trajectory avoids much of the 
overhead of successive calls to the normal Display routines, box is the window region in 
which painting may occur. The client must not try to paint outside box; this is not 
checked, flags controls the type of painting performed. If flags.gray « true, the gray brick 
is painted; otherwise, a bitmap is painted. Trajectory repeatedly calls proc for 
instructions. If proc returns a box having dims.w a 0 (such as window.nullBox), Iteration 
ceases and Trajectory returns. Otherwise dims.w # 0; Trajectory paints the brush and 
then loops to call proc again. The brush paints the returned Box in the window as follows. 
If a gray brick is being painted, the brick completely fills ihe returned Box. If a bitmap is 
being painted, the bitmap starts at a bit offset of <integer> from source, is Box. dims. h 
high, and has bp! pixels per line. The client may wish to alter the brush content along the 
trajectory by having source be a large bitmap containing several different brush patterns 
and having proc return the bit offset and Box.dims of the desired portion. (BitBlt.BitBltFlags 
are described in §21.2.2.) height and missesChildren are unused, proc must not call any 
procedures in Display or Window; doing so will result in a deadlock. 

21.3 Usage/Examples 



21.3.1 Special Topic: Direct Painting 

As described in the Window chapter, the standard way for a client to paint into its window 
is to update its data structures, invalidate the portion of its window that needs to be 
painted, and then call a window. Validate routine. Window responds by calling back into 
the client's display procedure to do the painting. 

The client may also paint directly into a window without going through window. Validate. 
However, this direct-painting approach is subject to several pitfalls and system bugs. 
Clients commonly choose direct painting only when high painting performance is 
required, such as dynamically extending an inverted selection while tracking the mouse 
or implementing a blinking caret. 

Pitfall 1: One consequence of doing direct painting is that the window's display procedure 
must not depend on Window clearing invalid areas for it. As described in the Window 
chapter, if clearingRequired » true, Window guarantees that when the display procedure 
is called to paint the window, all of the window's pixels that should be white indeed are 
white. In that situation, the window might contain any combination of its previous 
contents and erased areas. Notice that the following sequence of events might occur: 
Window clears invalid urea; then the client direct paints into some part of the invalid 
area; then Window calls the window's display procedure. In this situation, the parallel 
direct-paint activity has voided Window's guarantee of the content of the invalid area. To 
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handle this case, the display routine must erase or otherwise completely overpaint the 
invalid areas itself. 

Pitfall 2: A client can get into trouble when it wishes to change the state of the backing 
data being displayed within a display procedure and attempts to make the change by 
painting from the display procedure rather than by invalidating the affected area and 
painting later. The display procedure's paint is clipped to its invalid area list and thus 
fails to achieve the desired effect. There are several ways to solve this problem: 

• Do not change the backing data inside a display procedure. This approach matches 
nicely with the intended function of a display procedure. Oo not expect a display 
procedure to change data— its job is to repaint. 

• Have the display procedure just invalidate the areas affected by the data being 
changed. Because a validate is already in progress, it is not necessary to call 
Window. Validate. When the display procedure returns, it is called back with any new 
invalid areas that are waiting for it. 

• Have the display procedure call window.FreeBadPHosphorList before changing the 
data. This allows paint from the display procedure to affect the entire window, not 
just the invalid areas. 

21.3.2 Example 1 

The program fragments below demonstrate the use of Display in a window's display 
procedure. 

- Enumerated TYPEs for displaying the games background. 
Background: type « {gray, white}; 
background: Background gray; 

DisplayBoardSW: proc [window: window.Handie] ■ { 
~ TVifs is the body window's display procedure. 
vLine, hLine: window.Box; 
left, right, top, bottom: integer; 

FIndBounds: PROC [window: Window.Handie, box: Window.Box] a { 
left4-MiN[left, box.piace.x]; 
top<-MiN[top, box.place.y]; 
right «-iMAx[right, box. place.x * box.dims.w); 
bottom 4- MAX[bottom, box.place.y * box.dims.h]}; 

- Paint borders and background. 

oispiay.Biack[window: window, box: boardAndBorderBox]; 
PaintBackgroundfwindow: window, box: boardBox]; 
vLine«-[upperLeft, [lineWidth, (boardSize- 1)*unitH + 1]]; 
hLine «- [upperLeft, [(boardSize - 1)*unitW + 1, lineWidthj]; 
THROUGH [firstDimboardSize] oo 

oispiay.Black[window, vLinej; 

oispiay.Black[window, hLine]; 

vLine.place.x <— vLine.place.x •«• unitW; 
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hUne.place.y <~hLine.place.y •»• unitH; 

ENOLOOP; 



left top <- INTEGER.LAST; 

right <- bottom <-integer.first; 
window.EnumerateinvalidBoxes[FindBouncis] 



}; 



PaintBackground: PROC [window: Wmdow.Handle, box: window.Box] ■ { 
SELECT bacicground from 

gray « > Dispiay.Gray[window, box]; 
white > > Display. White(window, box]; 

ENDCASE 

}; 

PaintStone: public proc [who: BlackWhite, u, v: Dim, play: GVROINAL] > { 
center: window.Place; 
stoneBox: window.Box; 
numStr: string*- [3]; 

iF'ValidCoords[u, v] then return; 
center <- BoardToPlace[u, v]; 
StoneBox [ 

place: [centerx - stoneRadius, center.y - stoneRadius], 
dims: [stoneSize, stoneSize]]; 

paint a bitmap ttiat represents game pieces. 
Dispiay.Bitmapf 

window: boardSW, box: stoneBox, address: outerStone, 

bitmapBitWidth: stoneBpi, flags: Dispiay.paintFlags]; 
IF who > white then 
Oisplay.Bitmap[ 

window: boardSW, box: stoneBox, address: innerStone, 

bitmapBitWidth: stoneBpl, flags: eraseFlags]; 

}; 

CreateGoSWS: public procedure [ 

reference: NSFile.ReferenceRecord, name: Environment-Block ] 

returns [StarWindowSheil.Handle] a { 

" rfifs procedure is invoiced via a system menu. 

SZ: StarWindowSheil.Handle; 



starWindowSheil.SetPreferredDims [ sz, [592, 661] ]; 

- The display procedure is set here. Jlill 
boardSW <— starWindowSheii.CreateBody [ 
sws: sz. 
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repaintProc: DisplayBoardSW, 
bodyNotifyProc: TIPMe ]; 
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21.4 Index of Interface Items 



Item Page 

Arc: PROCEDURE 5 

BitAddress: type 2 

BitAddressFromPiace: procedure 3 

BitBltFiags: type 2 

bitFlags: BitBit. BitBltFiags 3 

Bitmap: procedure 3 

Black: procedure 2 

BlackParalleiogram: procedure 6 

boxFlags: BitBit.BitBltFlags 3 

Brick: type 4 

Circle: procedure 5 

Conic: procedure 5 

DashCnt: procedure 4. 

DstFunc: type 2 

Ellipse: procedure 5 

eraseFlags: BitBit.BitBltFlags 3 

fiftyPercent: Brick 4 

FixdPtNum:TYPE 6 

Gray: procedure 4 

Gray Trapezoid: procedure 7 

Handle: TYPE - 1 

Interpolater: type 6 

Invert: procedure 2 

Line: procedure 5 

LineStyle: type 4 

LineStyleObject:TYPE 4 

pai ntBitFlags : BitBit. BitBltFiags 3 

paintFlags: BitBit.BitBltFlags 2 

paintGray Flags: BitBit.BitBltFlags 3 

Parallelogram: TYPE 6 

Point: PROCEDURE 4 

replaceboxFlags: BitBit.BitBltFlags 3 

replaceFtags: BitBit.BitBltFlags 2 

replaceGray Flags: BitBit.BitBltFlags 3 

Shift: PROCEDURE 7 

textFlags: BitBit.BitBltFlags 2 

Trajectory: procedure 8 

TrajectoryProc: type 8 

Trapezoid: type 7 

White: procedure 2 

xorBoxFlags: BitBlt.BitBltFlags 3 

xorFiags: BitBit.BitBltFlags 2 

xorGrayFlags: BitBit.BitBltFlags 3 



22.1 Overview 



Divider maintains a table of entries in memory, each representing an icon. The entries 
may or may not be backed by files. Divider does not operate on these entries directly; it 
uses a oivider.ConvertProc and a Divider. GenericProc associated with each entry. 

Also associated with each entry is an NSFiie.Type used to identify the entry's 
Containee.lmpiementation, a label, and a pointer to instance-specific data for the entry. 

Associated with each divider when it is created is an NSFiie.Type. Divider automatically 
sets a Containee.lmpiementation for this file type that supports converting the divider to a 
file and opening the divider as a container window displaying the entries. 

Also associated with each divider is a CH. Pattern specifying a clearinghouse domain and 
organization. It is inherited from a parent divider and is passed to all entries through the 
Oivider.ConvertProc and the Oivider.GenericProc associated with each entry. When the 
divider is converted to a file, the pattern is automatically encoded in an attribute of the 
file. 

22.2 Interface Items 

22.2.1 Creating and Destroying 

Handle: type > long pointer to Object; 

Object: type; 

Create: procedure [ 
type: NSFiie.Type, 
name: xstring.Reader, 

initialSize: cardinal <-oivider.defauitlnitiaiSize, 
increment: cardinal f-Divider.defaultincrement, 
zone: uncounted zone <— nil] 
RETURNS [handle: Handle]; 
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Create creates a divider, type specifies the NSFiie.Type the divider has if it is converted to a 
file. A Containee.lm pie mentation is automatically set for this type, name specifi.es the name 
of the divider. It appears in the window header when the divider is opened, and it is the 
name of the file if the divider is converted to a file. The xstring. Reader bytes are copied. The 
divider is created with a table large enough to hold initiaiSize entries. If an entry is added 
when the table is full, the table grows by increment entries. Storage for the divider is 
allocated from zone. If zone is defaulted, storage is allocated from a heap maintained by 
Divider. 



Destroy: procedure [handle: Handle]; 

This releases all storage associated with the given divider, handle is no longer valid when 
this procedure returns. 



22.2.2 ConvertProc and Generic Proc 



ConvertProc: type » procedure [ 
data: long pointer, 
pattern: CH.Pattern, 
target: Sciection.Target, 
zone: uncounted zone, 
info: Seiection.Conversionlnfo [convertfl]] 
returns [value: Selection. Value]; 

A ConvertProc is the same as a Selection.ConvertProc except that it has the extra argument, 
pattern, that specifies a clearinghouse domain and organization. (See the Selection 
interface for the definition of the other arguments.) Whenever the divider is requested to 
convert one of its entries, it calls the ConvertProc associated with an entry, with pattern 
set to the domain and organization associated with the divider, 

GenericProc: type - procedure [ 
atom: Atom. ATOM, 
data: long pointer, 
pattern : ch .Pattern , 

changeProc: containee.ChangeProc nil, 
changeProcData: long pointer ^ nil] 
returns [long unspecified]; 



A GenericProc is the same as a Containee. GenericProc except that it has the extra argument, 
pattern, that specifies a clearinghouse domain and organization. (See the Containee 
interface for the definition of the other arguments.) Whenever the divider is requested to 
operate on one of its entries, it calls the GenericProc associated with an entry, with pattern 
set to the domain and organization associated with the divider. 



DividerConvertProc: ConvertProc; 
DividerGenericProc: GenericProc; 



These procedures may be associated with entries that themselves are dividers. In this case 
the Handle associated with the divider should be provided as the instance-specific data 
handle. See below for an e.xample of a divider contained in another divider. 
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22.2.3 Adding and Finding Entries 

AddEntry: procedure [ 
handle: Handle, 
type: NSFii«.Typer 
label: xstring.Reader, 
data : long pointer <- nil, 
convertProc: ConvertProc «- nil, 
genericProc: GenericProc <-NiL]; 

AddEntry adds an entry to the divider specified by handle, type obtains the 
Containee.lmplementation for the entry, label is used to label the entry in the divider's 
container window. The xstring. Reader bytes are copied, data is item-specific data for the 
entry that is passed to the ConvertProc and GenericProc associated with the entry. If 
convertProc or genericProc is defaulted, the divider uses the corresponding procedure in 
the entry's Containee.lmplementation. 

FindEntry: procedure [handle: Handle, type: NSFiie.Type, 
label: xstring.Readerl 

returns [found: boolean, entryOata: long pointer); 

FindEntry finds the entry in the divider handle with the specified type and label, found 
indicates whether the item was in the divider. entryOata is the data associated with the 
entry, if it was found. FindEntry is defined in DividerExtra.mesa. 

FindOr AddEntry: procedure [handle: Handle, type: NSFiie.Type. 
label: xstring.Reader, data: long pointers- nil, 
convertProc: ConvertProc nil, 
genericProc: GenericProc nil] 
returns [found: boolean, entryOata: long pointer]; 

FindOrAddEntry finds the entry in the divider handle with the specified type and label, 
and adds an entry if it was not found, found indicates whether the item was in the 
divider. entryOata is the data associated with the entry, if it was found. FindOrAddEntry 
is defined in DividerExtra.mesa. 

22.3 Usage/Examples 

22.3.1 Fragment from Directory ImpLmesa 

This fragment is from Oirectoryimpl.mesa, which implements the Directory interface. It 
shows the implementation of oirectory.AddOividerEntry and the mainline code to create the 
top-level directory dividers. See the CHOivider interface for more examples. 

- File types for the directory implementation ~ 
directory: starFiieTypes.FileType « 
folder: StarFiieTypes.FileType a 
workstation: StarFiieTypes.FileType > 
user: StarFiieTypes.FileType a 
^^■i*^ domain: StarFiieTypes.FileType 
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-- TTie reference for the prototype folder — 
prototypeReference: NSFiie.Reference 

- Handles for the top-level dividers ~ 

dividers: array oiVectory.OividerType of oivider.Handle ^ all [nil]; 

AddDividerEntry: public procedure [ 
divider: Directory. OividerType, 
type: NSFito.Type, 
label: xstring.Reader, 
data: long pointer nil, 
convertProc: oivider.ConvertProc «- nil, 
genericProc: Divider.GenericProc f-NiL] ■ 

BEGIN 

Divider.AddEntry [ 

handle: dividers(divider], 
type: type, 
label: label, 
data: data, 

convertProc: convertProc, 
genericProc: genericProc]; 

ENO; 

» Create the top-level dividers (top will back the directory icon) — 
dividers[top] *- oivider.Create [directory, stringOirectory]; 
dividers[ws] 4- oivider.Create [workstation, stringWorkstation]; 
dividers[user] «- oivider.Create [user, stringUser]; 



-- Insert the workstation divider into the directory — 
Oirectory-AddDividerEntry [ 

divider: top, 

type: workstation, 

label: stringWorkstation, 

data: dividers[ws], 

convertProc: Divider.DividerConvertProc, 
GenericProc: oivider.OividerGenericProc]; 



- Insert the user divider into the directory - 
oirectory.AddDividerEntry [ 

divider: top, 

type: user, 

label: stringUser, 

data: dividers[user], 

convertProc: Divider.DividerConvertProc, 

genericProc: Divider.OividerGenericProc]; 



- Insert the prototype folder into the workstation divider — 

- fNote; this is an actual file that will use the folder implementation) - 
Oirectory.AddDividerEntry [ 

divider: ws. 
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type: folder, 

label: stringPrototypes, 

data: @prototypeReference]; 



Divider 



22.4 Index of Interface Items 



Item Page 

AddEntry: procedure 3 

ConvertProc: type 2 

Create: procedure 1 

Destroy: procedure 2 

oivider.ConvertProc:TYPE 2 

OividerConvertProc: ConvertProc 2 

OividerGenericProc: GenericProc 2 

FindEntry: procedure 3 

FindOrAddEntry: procedure 3 

GenericProc: type 2 

Handle: type 1 

Object: type 1 



23.1 Overview 



Viewpoint provides a facility that permits clients to register procedures that are to be 
called when specified events occur. For example, a client may wish to be notified whenever 
a document is closed, or perhaps just the next time a document is closed. Clients need not 
know which module can cause the event. 

23.2 Interface Items 

23.2.1 Registering Dependencies 

A client wishing to be notified of some future event calls either AddDependency or 
AddDependencies, specifying the EventType and an AgentProcedure to be called when 
the event occurs. Note: ViewPoint need not know in advance what EventType is 
implemented, nor which modules implement them. 

AddDependency: procedure [ 
agent: AgentProcedure, 
myOata: long pointer to unspecified, 
event: EventType, 
remove: FreeDataProcedure nil] 
returns [dependency: Dependency]; 

AddDependencies: procedure [ 
agent: AgentProcedure, 
my Data: long pointer to unspecified, 
events: long descriptor for array of EventType, 
remove: FreeDataProcedure *- nil] 
RETURNS [dependency: Dependency]; 

AgentProcedure: type ■ procedure [ 
event: EventType, 

eventData, myData: long pointer to unspecified] 
RETURNS [remove, veto: boolean false]; 
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FreeOataProcedure: TYPE ■ procedure [mydata: long pointer to unspecified]; 
Dependency: type [2]; Opaque - 

A dependency may be added to an event or an entire set of events by calling 
AddDependency or AddDependencies. Both of these procedures return a private type, 
Dependency, that uniquely identifies that set of dependencies. The value returned may be 
saved and subsequently used in a call to RemoveDependency, which removes the 
dependency or dependencies associated with the earlier AddXXX call. The 
AgentProcedure may also remove the dependency, as discussed below. 

When the specified event occurs, agent is called with the EventType, the eventData for 
the event, and the client data passed as myData. If a client wishes to veto the event (for 
instance, to disallow a world-swap), its AgentProcedure should return veto: true. This 
aborts the notification; that is, no other clients dependent on the event are notified. 
However, there is no guarantee of the order in which multiple clients are notified. If any 
client vetoes the event, the call to Notify returns true. There is no way to prevent a client 
from vetoing; instead, implementors of events that should not be vetoed should raise an 
ERROR if Notify returns true. To remove its dependency on an event, a client's 
AgentProcedure should return remove: true. If the dependency is removed and a 
FreeDataProcedure was provided, it is called at this time to allow the client to free any 
private data. 

EventType: typIe ■ Atom.ATOM; 

The ATOM (strings) used to identify different everits must of course be distinct. The 
following examples are possibilities of how this could be managed. (1) By a central 
authority whose job it is to guarantee uniqueness of EventTypes. This could be the same 
person in charge of other such allocations, such as NSFile types. (2) By a hierarchical 
naming structure, managed by a distributed authority. (3) By a file that lists all known 
EventTypes within a given system; this file is managed by the Librarian to ensure against 
parallel allocation of new EventTypes. (In effect, this is the same as case 1, but the 
Librarian takes the place of the central authority.) 

RemoveDependency: proc [dependency: Dependencyj; 

NoSuchOependency: error; 

If RemoveDependency is called with a Dependency that is invalid (possibly because the 
dependency has already been removed), it raises the error NoSuch Dependency. 



23.2.2 Notification 

Notify: procedure [event: EventType, eventData: long pointer to unspecified nil] 
RETURNS [veto: boolean]; 

When the event occurs, the implementor calls Notify, giving it the EventType for the 
event and any implementation-specific data (eventData) required by the client. 
(Presumably it is uncommon for a single operation to wish to Notify more than one event; 
this is why Notify does not take an array argument.) The Event interface then invokes 
each AgentProcedure that is dependent on the EventType. Bach AgentProcedure is given 
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the EventType causing the notification, the client data provided when the dependency was 
created, and the eventData given by the implementor in the call to Notify. 

23.3 Usage/Examples 

The Event database is monitored to disallow changes while a Notify is in progress. An 
AgentProcedure is allowed to call Notify; that is, one event may trigger another. 
However, an AgentProcedure must not call AddDependency or RemoveOependency, or 
deadlock will result. Because it is relatively common for an AgentProcedure to wish to 
remove its own dependency, the AgentProcedure can return remove: true to cause the 
dependency to be removed. If the dependency was added via AddOependencies, then ail of 
the dependencies created by that call are removed. The dependency is removed even 
though some later client of the same event might choose to veto the event. (If an earlier 
client has already vetoed, of course, then this AgentProcedure never gets called.) If an 
application requires that a dependency be removed only if the event is not vetoed, the 
implementor can notify a second event that informs clients whenever the first event is 
vetoed. 

Three notes regarding the preceding paragraph: First, an AgentProcedure may get called 
twice even if it always returns remove: TRUE because two separate processes may be doing 
parallel calls to Notify. Once an AgentProcedure returns remove: true, no subsequent 
calls to Notify invoke that dependency, but any parallel calls in progress complete 
normally. Second, because an AgentProcedure might be invoked at any time, it is a bad 
idea to call Add/RemoveOependency from within a private monitor, lest it lock trying to 
modify the Event database while a Notify is inside the AgentProcedure trying to grab the 
lock. However, the Notify call may very well be within the implementor's monitor, which 
means the AgentProcedure's use of the eventOata is t3npically limited. Finally, if an 
AgentProcedure needs to call Add/RemoveOependency, it may get the desired effect by 
PORKing the call so that it takes place shortly after the Notify already in progress. 

23.3.1 Example 1 

- Module interested in an event 

eventType: Ev«nt. EventType ^-Atom.MakeAtom [ "Sam pleE vent" L]; 

EventAction: Event. AgentProcedure ■ { 

Do appropriate t/i/ng for eventType ~ }; 

Ev«nt.AddOependency [ 
agent: EventAction, 
myOata: nil, 
event: eventType]; 

- Moduie that signals the event 

eventType: Event.EventType Atom.MakeAtom ["SampieEvent"L]; 
eventOata: - Relevant info, a record, a window handle, etc. --; 
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[] «- Event.Notify [event: eventType, eventOata: eventData]; 

23.3.2 Example 2 

— Declare event and eventData — 
desktopWindowAvailabie: Event. EventType; 
desktopWindowHandle: window.Handle nil; 

" Declare AgentProcedure 
Startup: Event.AgentProcedure ■ { 

If eventOata » nil then return [veto: true]; 

desktopWindowHandle 4- eventData }; 

" Register event— this is mainline code — 

[] <~ Event.AddDependency [Startup, nil, desktopWindowAvailabie]; 

" In Desi(top code, another module, notify occurrence of the event 
[] Event.Notify [desktopWindowAvailabie, window]; 
" Window is desktop window — 
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23.4 Index of Interface Items 



Item Page 

AddDependencies: procedure 1 

AddOependency: procedure 1 

AgentProcedure: type 1 

Dependency: type 2 

EventType: type 2 

FreeOataProcedure: type 2 

NoSuchOependency: error 2 

Notify: procedure 2 

RemoveOependency: procedure 2 
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24.1 Overview 

FileContainerShell provides a simple way to implement a container application that is 
backed by an NSFiie. FileContainerSheil takes an NSFile and column information (such as 
headings, widths, formatting) and creates a FileContainerSource, a StarWindowShell, and 
a ContainerWindow body. (See also the FileContainerSource, ContainerSource, 
StarWindowShell, and ContainerWindow interfaces) Most NSFIIe-backed container 
applications can use this interface, thereby greatly simplifying the writing of applications 
such as Folders and File Drawers. 

24.2 Interface Items 

24.2.1 Create a FileContainerShell 

CreateX: procedure [ 
file: NSFiie.Reference, 

columnHeaders: Containerwindow.CoiumnHeaders, 
columnContents: FileContainerSource.ColumnContents, 
regularMenuitems,topPusheeMenultems: MenuOata.ArrayHandle <-niu 
scope: NSFiie.Scope [], 

position: ContainerSource.itemlndex <— 0, 
options: FileContainerSource.Options <— [], 

access: ContainerWinclowExtra3.Access ContainerWindowExtraJ.fullAccess] 
RETURNS [shell: StarWindowShell.Handle]; 

Create: procedure [ 
file: NSFile. Reference, 

columnHeaders: Containerwindow.CoiumnHeaders, 

columnContents: FileContainerSource.ColumnContents, 

regularMenuitems, topPusheeMenuitems: MenuOata.ArrayHandle <— nil, 

scope: NSFiie.Scope [], 

position: ContainerSource.ltemlndex <-0, 

options: FileContainerSource.Options <— []] 

returns [shell: starwindowSheii.Handle]; 
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Create and CrsateX create a StarWindowSheil with a container window as the body 
window, file the backing for the container; it must be an NSFile with children. 
columnHeaders and columnContents specify all the necessary information about the 
columns to be displayed for the open container. (See the ContainerWindow and 
FileContainerSource interfaces for the specifics of the headers and contents.) scope 
specifies ordermg, filtering, and direction, if any. position indicates the item that should 
be displayed first, access specifies the ContainerWindow access. (See the 
ContainerWincaow interface for details. regularMenultems and topPusheeMenultems 
are the menu i-^ms that the client would like to put in the header of the StarWindowSheil. 
Create puts th-se items in the header along with its own menu items, such as Show Next 
and Show Pre' ious. Fine point: The client is responsible for putting any bottomPusheeCommands in the 
window header. OeateX is defined in FileContainerShellExtra.mesa. 

24.2.2 Operations on the Shell 

GetContainerWindow: procedure [shell: starWindowShsil.Handle] 
RETURNS [window: window.Handle]; 

Returns the container window that was created by the Create procedure. May raise 
ContainerWindow.Error[notAContainerWindow] if the shell does not have a container 
window in it. 

GetContainerSource: procedure [shell: starWindowSheii.Handle] 

RETURNS [source :ContainerSource.Handle]; 

Returns the container source that was created by the Create procedure. May raise 
ContainerWindow.Error[notAContainerWindow] if the shell does not have a container 
window in it. 

24.3 Usage/Examples 

24.3.1 Example: Creating a FileContainerShell and Specifying Columns 

The following example presents the procedure CreateFileSWS, which takes an 
NSFile. Reference and creates a file container shell with two columns: the name of the file 
and a version date. (See the ContainerSource interface for details on columns.) The name 
column uses the predefined ContainerSource.NameColumn; the version column is given in 
the example. The version column differs from the standard ContainerSource.OateCoiumn in 
that it displays the last modified date for directories instead of — . 

ContentSeq: TYPE « record [ 

sequence cols: cardinal of FileContainerSource.ColumnContentSinfo]; 
HeaderSeq: type « record [ 

SEQUENCE cols: CARDINAL OF containerwindow.ColumnHeaderinfo]; 
NumberOfColumns: CARDINAL a 2; 

Z: UNCOUNTED ZONE a 

CreateFileSWS: procedure [reference: NSFiie. Reference] 

RETURNS [StarWindowSheii.Handle] ■ 

begin 

shell: StarWindowSheii.Handle; 
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headers: long pointer to HeaderSeq MakeColumnHeadersn; 
contents: long pointer to ContentSeq *- MakeColumnContentsH; 
shell <- FlleContalnerSheli.Create( 
file: reference, 

columnHeaders: DESCRiPTOR[headers], 

cot u m nConte nts : DESCRiPTOR{contents]] ; 
z.FREE[@headers]; 
z.FREE[@contents]; 
RETURN[sheil]; 
end; 

OateFormatProc: FiieContainerSource.MuitlAttributeFormatProc > 

BEGIN 

" If non-directory, show createdOn date. For directory, sfiow last date modified 

(ttte last time anything was changed in directory) — 
template: xstnng.ReaderBody <— 

xstring.FromSTRINGC <2>-<6>-<4><8>:<9>:<10>'Ll; 
XTime.Append( 
display String, 

IF attrRecord.isOirectOry THEN attrRecord.modif iedOn ELSE attrRecord.createdOn, 
©template]}; 
end; 

MakeColumnContents: procedure 

RETURNS [coiumnContents: long pointer to ContentSeq] » 
begin 

dateSeiections: NSFiie.Seiections [interpreted: [ 

isOirectory: true, createdOn: true, modifiedOn: true]]; 

coiumnContents <- z.NEW(ContentSeq[NumberOfColumns]; 
columnContents{0] <- FileContainerSource.NameColumn[]; 
columnContents[1] 4~[multipleAttributes [attrs: dateSeiections, formatProc: 
OateFormatProc]]; 

return [coiumnContents]; 
end; 

MakeColumnHeaders: procedure 

returns [columnHeaders: long pointer to HeaderSeq] ■ 

BEGIN 

columnHeaders z.NEW[HeaderSeq[NumberOfColumns]]; 
columnHeaders[0] [ 
width: 367, 

heading: XString.FromSTRING["NAME"] ]; 
columnHeaders[1] <-[ 
width: 135, 

heading: xstring.FromSTRiNG["VERSION OF"] ]; 
RETURN [columnHeaders]; 
end; 
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24.4 Index of Interface Items 



Item Page 

Create: procedure 1 

CreateX: procedure 1 

GetContainerSource: procedure 2 

GetContainerWindow: procedure 2 



FileContainerSource 



25.1 Overview 

FileContainerSource supports the creation of NSFile-backed container sources (see 
ContainerSource). It also provides facilities for specifying the columns that will be 
displayed for each item in the source. 

FileContainerSource implements all the procedure types described in the ContainerSource 
interface, as well as all the procedures described below. 

25.2 Interface Items 

25.2.1 Creation 

Options: type ■ record [ 
readonly: BOOLEAN <-false]; 

Create: procedure [ 
file: NSFiie, Reference, 
columns: ColumnContents, 
scope: NSFiie.Scope [], 
options: Options [] 1 
returns [source: ContainerSource.Handle] ; 

Creates a container source backed by file, which must be an NSFiie with children, columns 
describes the information that should be displayed for each entry in the container, 
columns is copied by this procedure, so the client may release any storage associated with 
columns after calling Create, scope specifies the range of files that is displayed. The 
caller of Create is responsible for the storage in the scope parameter; FileContainerSource 
will not copy it. It can be destroyed at the same time the source is destroyed. Typically the 
client saves the pointer to scope storage in same place as source handle, options specifies 
global information about the container source. The container window manages display 
formatting. (See the ContainerWindow and FileContainerShell interfaces.) 
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25.2.2 Specifiying Columns 



Columns may be specified when a file container source is created. Each column represents 
information that is displayed for each item. The container window requests the columns 
one at a time in the form of strings. In a file container source, each column must be based 
on some combination of NSFile attributes. For each column, the creator of the file container 
source specifies which attributes are required to format a string for that column and 
supplies a procedure that is called with the specified attributes. When the files in the 
source are enumerated, the procedure for a particular column is called with the values of 
the specified attributes for each file, which should be used to generate the string for that 
file. 

ColumnContents: type ■ 

LONG DESCRIPTOR FOR ARRAY OF CoiumnContentsinfo; 

ColumnContents describes a set of columns in which each column is some information 
that is displayed for each item in the container display. The columns are displayed in the 
order given by this array. 

ColumnType:TYPE ■ {attribute, extended Attribute, multipleAttributes}; 

CoiumnContentsinfo: TYPE ■ record [ 
info: SELECTtype: CoiumnlypeFROM 
attribute « > [ 

attr: NSFiie.AttributeType, 

formatProc: AttributeFormatProc <-nil], 
needsDataHandle: boolean <- false], 

extended Attribute ■ > [ 

extendedAttr: NSFUe.ExtendedAttributeType, 

formatProc: AttributeFormatProc <-nil, 
extendedAttr! bute « > [ 

extendedAttr: NSFiie.ExtendedAttributeType, 

formatProc: AttributeFormatProc *-nilI, 
multipleAttributes a > [ 

attrs: NSFiie.Selections, 

formatProc: MultiAttrlbuteFormatProc <-nil], 
endcase]; 

CoiumnContentsinfo describes a single column of information that can be displayed for 
each item in a container display. Each column may be backed by one of three things: an 
NSFlle interpreted attribute (the attribute variant), and NSFile extended attribute (the 
extendedAttribute variant), or some combination of several attributes (the 
multipleAttributes variant). The attribute and extendedAttribute variants both take a 
specification of what attribute is being described (attr and extendedAttr) and an 
AttributeFormatProc that is called to render the attribute as a string. If needsDataHandle 
■ TRUE, then a valid Containee.OataHandle is passed to the format procedure as the 
containeeOata parameter, else the contalneeOata parameter is nil. If the column needs a 
Containee.DataHandle in order to format it, then needsDataHandle should be true. This 
addition is for performance: obtaining a Containee.DataHandle requires an extra access to 
the file, thus slowing up the enumeration. The multipleAttributes variant is for columns 
that may require more than one attribute. (The typical example is the SIZE column in 
folders, in which some items display the numberOfChildren attribute and others display 
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the sizeinPages attribute, depending on the isOirectory attribute.) attrs specifies all the 
attributes required for this column. formatProc is the procedure that is called to format 
the column. 

See the common types of columns provided below in the section on commonly used 
columns. 

AttributeFormatProc: type ■ procedure [ 
containeeimpi : containee.lmplementation, 
containeeData:containee.OataHandle, 
attr: NSFiie. Attribute, 
dispiayString: xstring. Writer]; 

When the container display mechanism displays a column that represents an NSFile 
attribute, it calls the AttributeFormatProc specified for that column, attr contains the 
attribute to be formatted for display. dispiayString returns a formatted string that 
represents the desired attribute, containeeimpi may be used to make calls on' the 
underlying implementation of the item being displayed. 

Muiti AttributeFormatProc: type ■ procedure [ 
containeeimpi : Containee.implementation, 
containeeOata: Containee.OataHandle, 

attrRecord: NSFiie. Attributes, - long pointer ro NSFiie.AttributesRecord 
dispiayString: xstring. Writer]; 

When the container display mechanism displays a column that represents multiple NSFile 
attributes, it calls the Multi AttributeFormatProc specified for that column. attrRecord 
contains the attributes to be formatted for display. dispiayString is used to return a 
formatted string that represents the desired attribute containeeimpi may be used to 
make calls on the underlying implementation of the item being displayed. 

25.2.3 Operations on Sources 

Getltemlnfo: procedure [ 

source: ContainerSource.Handle, itemlndex: ContainerSource.ltemlndex] 
returns [file:NSFiie.Reference,type: NSFUe.Type]; 

Returns an NSFile.Ref erence and type for the specified item. 

Info: procedure [source: ContainerSource.Handle] 
RETURNS [ 

file: NSFiie.Reference, 
columns: ColumnContents, 
scope: NSFiie.Scope, 
options: Options]; 

The Info procedure returns information about a file container source; the information 
returned is the same information that was used to create the source (see the Create 
procedure). 

Isit: PROCEDURE [sOurce: ContainerSource.Handle] RETURNS [BOOLEAN]; 
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isit returns true if source is a file container source. 

ChangeScope: procedure [source: containerSource.Handte, newScope: NSFiie.Scope]; 

AUows the scope (passed in to Create) to be changed. A call to ChangeScope is typically 
followed by a source.ActOn[reiist], then aContainerWindow.Update. 

Rebuildltem: procedure [source: ContairarSource.Handle, item: ContainerSource.ltemindex]; 

Rebuildltem causes the FileContainerSource to rebuild itenn, for example after a client has 
changed an attribute that is displayed in a column of the source. Note : the client must 
call the appropriate ChangeProc to get the container window to repaint properly. 

25.2.4 Commonly Used Columns 

These predefined procedures can be used in building a ColumnContents array. 

IconColumn: procedure 

RETURNS [attribute CoiumnContentstnfo]; 

IconCoiumn represents a column with a small icon picture in it. The small picture is 
obtained from the containeeimpl.smallPicture that is passed in. 

NameColumn: procedure 

RETURNS [attribute ColumnContentslnfoj; 

NameColumn represents a column with the file's name in it. 

SizeColumn: procedure 

RETURNS [multipieAttributes CoiumnContentslnfo]; 

SizeColumn represents a column with the file's size in it, as follows: If the file has the 
isOirectory attribute, the numberOfChiidren attribute is displayed with the label 
"Objects"; if the file does not have the isDIrectory attribute, the sizelnPages attribute is 
displayed with the label "Disk Pages". 

OateColumn: procedure 

RETURNS [multipieAttributes CoiumnContentslnfo]; 

OateColumn represents a column with the file's creation date in it, as follows: If the file 
has the isOirectory attribute, dashes ( — ) are displayed; if the file does not have the 
isOirectory attribute, the createOate attribute is displayed. 

VersionColumn: procedure 

RETURNS [attribute CoiumnContentslnfo]; 

VersionColumn represents a column with the file's version in it. VersionColumn is 
defined in FileContainerSourceE xtra. mesa. 
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NameAndVersionColumn: procedure 

RETURNS [muitipieAttributes CoiumnContentslnfo]; 

NameAndVersionCoiumn represents a column that has the file's name and version 
appended with an exclamation point in between, such as Foo!3. NameAndVersionCoiumn 
is defined in FileContainerSourceExtra.mesa. 

25.3 Usage/Examples 

25.3.1 Example: Specifying Columns using FileContainerSource 

The following example presents the procedure l\/lai<eFolderLii(eSheil, which takes an 
NSFtie. Reference (Containee.OataHandle) and creates a file container shell with the 
number of columns dependent on some internal procedures. (See the ContainerSource 
interface for details on columns.) The columns use the predefined columns such as 
Conta iner Source. Nam eCoi um n . 

Columns: type ■ {icon, name, version, nameAndVersion, size, createDate}; 
HeaderSeq: type a record (sequence cols: cardinal of containerwindow.ColumnHeaderInf o]; 
ContentSeq: TYPE ■ record! 

sequence coIs: CARDINAL OF FiieContainerSource.ColumnContentslnfo]; 
ColumnArray:TYPE ■ array {icon, name, version, size, date} of cardinal; 
columnWidths: long pointer to CoiumnArray 4-z.NEw(ColumnArray <-null]; 

CiientsGenericProc: Containee.GenericProc ■ 
< <[atom: Atom.ATOM, 
data: Containee.OataHandle, 
changeProc: Containee.ChangeProc nil, 
changeProcData: long pointer <- nil] 

RETURNS [long UNSPECIFIED] > > 
BEGIN 

SELECT atom FROM 
open ■ > RETURN [ 

MakeFolderLikeShell [ 
data: data, 

changeProc: changeProc, 
changeProcOata: changeProcData] ]; 



ENDCASE ■ > RETURN [ oldFolder.genericProc [atom, data] ]; 
end; 

FreeColumnContents: public procedure [col umnContents: long pointer to ContentSeq] « 

BEGIN 

z.free[@coI umnContents]; 
end; 

FreeColumnHeaders: public procedure [columnHeaders: long pointer to HeaderSeq] a 

BEGIN 



25-5 



25 



FileContainerSource 



z.FREE[@coiumnHeaders]; 
end; 

MakeFolderLikeShell: procedure [ 
data: Containee.OataHandle, 
changeProc: Containee.ChangeProc <-niu 
changeProcOata: long pointers- nil] 

RETURNS [shell: StarWindowSheil.Handle] ■ { 

file: NSFiie. Reference; 

columnHeaders: long pointer to HeaderSeq MakeColumnHeadersn; 
columnContents: long pointer to ContentSeq «~MakeColumnContents[]; 



mydata: Data z.new [DataObject <~ [ 
cd: data, 

changeProc: changeProc, 
changeProcData: changeProcOata]]; 

isLocai: boolean; 

begin enable 

UNWIND • > { 

z.FREE[@mydata]; 

FreeColumnHeaders [columnHeaders]; 
FreeColumnContents [columnContents]; 

}; 



shell <- FileContainerSheli.Create [ 
file: file, 

columnHeaders: OESCRiPTOR[columnHeaders], 

columnContents: OE5CRiPTOR[columnContents], 

regularMenultems: if 'isLocal then remoteRegularMenultems else nil); 

IF shell ■ NiLTHEN RETURN [shell]; 

starwindowSheii-SetlsCloseLegalProc [shell. Closing]; 
context.Create[context, mydata, OestroyContext, shell]; 
FreeColumnHeaders [columnHeaders]; 
FreeCol u mnContents [col um nContents] ; 
starwindowSheiuSetPreferredDims [ shell, [700, 0] ]; 

RETURN [shell]; 
end; - ENABLE 
} 

MakeColumnContents: public procedure returns [columnContents: long pointer to 
ContentSeq] ■ 

BEGIN 

i: INTEGER <--1; 

columnContents z.NEw[ContentSeq[CountColumns[]]]; 
IFShowlcon[]THEN 
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coiumnContents[i <— i + 1] <~FileContainerSource.iconColumn[]; 
— Procedures called below are not neccessary to the example. 
columnContentsIi <-i + 11*- 

iF ShowNameAndVersion{] 

THEN FileContainerSourceExtra.NameAndVersjonCoiumn[l 

ELSEFileContainerSource.NameColumnn; 

IF ShowVersionQ then 

COiumnContents[i 4-i * 1] 4~FileContainerSourceExtra.VersionColumn[]; 
iFShowSizenTHEN 

columnContents[i <- i * 1] f-FileContainerSource.SizeCoiumnG; 
IF ShowCreateOateG then 

coiumnContents[i <- i * 1] 4-FiieContainerSource.OateColumnn; 
return [coiumnContents]; 
end; 
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25.4 Index of Interface Items 



Item Page 

AttributeFormatProc: type 3 

ChangeScope:PROCEOURE 4 

CoiumnContents: type 2 

CoiumnContentsinfo: type 2 

CoiumnType: type 2 

Create: procedure 1 

OateColumn: procedure 4 

Getlteminfo: procedure 3 

IconColumn: procedure 4 

Info: procedure 3 

ISit: procedure 3 

MultiAttributeFormatProc: type 3 

NameColumn: procedure 4 

NameAndVersionColumn: procedure 5 

Options: type 1 

Rebuiiditem: procedure 4 

SizeCoiumn: procedure 4 

VersionCoiumn: procedure 4 



Form Window 



26.1 Overview 

The FormWindow interface allows clients to create and manipulate form items in u 
window. 

There are several types of items, each of which serves a different purpose and behaves 
differently for the user. All items except tagonly and command have a current value that 
the client and user can obtain and set. The user obtains the current value of an item by 
simply looking at it and sets the current value of an item by pointing at it appropriately 
with the mouse. The client obtains and sets the value of items by calling appropriate 
FormWindow procedures. 

A boolean item is an item with two states (on and off, or TRUE and FALSE). A boolean 
item's value is of type boolean. 

A choice item has an enumerated list of choices, only one of which can be selected at any 
point in time. A choice item's value is of type FormWindow.Choicelndex. 

A multiplechoice item is a choice item that can have an initial value of more than one 
choice selected, but any succeeding values can have only one choice selected. A 
multiplechoice item's value is of type long OESCRrPTOR for array of cardinal. 

A text item is a user-editable text string. It contains nonattributed text only. A text item's 
value is of type xstring.ReaderBody. 

A decimal item is a text item that has a value of type XLReai.Number. 
An integer item is a text item that has a value of type long integer. 

A command item allows a user to invoke a command. When the user clicks oyer a 
command item, a client procedure is called. 

A tagonly item is an uneditable, nonselectable text string. 

A window item is a window that is a child of the FormWindow. It can contain whatever 
the client desires. A window item's value is a window.Handle. A client must provide its own 
TIP. Notify Proc and window display proc for the window item. 
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26. 1. 1 Creating a Form Window 



A client creates a FormWindow by calling FormWindow.Create. Create does not actually 
create a window; it takes an already existing window and turns it into a FormWindow. 
Windows are usually created by calling starWindowSheil.CreateBody. 

The client supplies a MakeltemsProc and optionally a LayoutProc to FormWindow.Create. 
Create calls these two client procedures, first the MakeltenfisProc and then the 
LayoutProc. In the MakeltemsProc, the client creates the individual items in the form by 
calling FormWindow procedures that make items (see §26.1.2 and §26.2.2). In the 
LayoutProc, the client specifies where each created item should be positioned in the 
window by calling FormWindow procedures that specify layout (see the sections labeled 
Layout in this chapter). 



26.1.2 Making Form Items 

There is a procedure for making each type of item: MakeBooleanltem, MakeCholceltem, 
MakeCommandltem, MakeDecimalitem, Makelntegerltem, MakeMultipleChoiceltem, 
MakeTagOnlyltem, MakeTextltem, MakeWlndowitem. Each item must have a unique 
"key", a FormWindow. ItemKey This is a cardinal supplied by the client to each 
MakeXXXItem call. This key is then used in any future calls to manipulate that item, such 
as to get the value of the item. The key must be unique within the FormWindow. 



All items have some common characteristics and some type-unique characteristics. The 
common ones are described here. Every item can have a tag that appears to the left of the 
item and a suffix that appears to the right of the item. An item can have a box drawn 
around it or not. The default is to draw the box. Items can be read-only (that is, the user 
cannot change the value of the item). Items can be visible or invisible, and invisible items 
can either take up white space in the window or not. See §26.2.2 for more details. 



26.1.3 Getting and Setting Values 



Every item that has a value that the user can change (all e.xcept tagonly and command 
items) also has procedures for the client to get and set the value. These are: 



GetBooieanitemVaiue 

GetChoiceltemValue 

GetDecimalitemVaiue 

GetlntegerltemValue 

GetMuitipleChoiceltemVaiue 

GetTextitemValue 

GetWindowltemVaiue 

LookAtTextitem Value 



OoneLookingAtTextltem Value 

SetBooleanitemVatue 

SetChoiceltemValue 

SetOecimalltemValue 

SetlntegeritemValue 

SetMuitipleCholceitemValue 

SetTextitemValue 
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Note: FormWindow handles all allocation of storage for values of items. The client need 
not keep copies of item values while the FormWindow exists. Obtaining the current value 
of an item is a simple call to one of the GetXXXItemVaiue procedures. This makes it easy to 
ensure that the internal value of an item is always in sync with the display. (See §26.2.3 

for more details.) Pine point: This storage allocation scheme is opposite to the one used by XDC's FormSW, 
where the client owns the storage for items. 

26.1.4 "Changed** BOOLEAN 

Every item that has a value that the user can change (all except tagonly, command, and 
window items) has a "changed" boolean associated with it. All items are created with this 
boolean set to false. FormWindow automatically sets this boolean to true whenever the 
user changes the item. This allows the client to determine which items have changed 
when, for example, the user selects Done or Apply on a property sheet. The client is 
responsible for resetting the changed boolean to false by calling ResetChanged or 
ResetAIIChanged after examining the changed boolean with HasBeenChanged or 
HasAnyBeenChanged. See §26.2.1 for more detail. 

Boolean and choice items can have a client-supplied procedure that is called whenever the 
item's value changes (see BooieanChangeProc and ChoiceChangeProc in §26.2.1 and 
26.2.2. The client may also supply a GiobalChangeProc that is called whenever any item 
changes (see §26.2.1). 

26.1.5 Visibility 

Each item is either displayed in the form window or not. If an item is displayed in the form 
window, it is visible. If an item is not currently displayed, it is either invisible or 
invisibleGhost. If it is invisible, it does not take up any space on the screen (that is, any 
items below it move up to take its screen space. If an item is invisibleGhost, the space that 
it would occupy were it visible is white on the screen). An item's visibility can be changed 
at any time by calling SetVisibiilty (see §26.2.5.) 

26.1.6 Layout 

Items in a form window are laid out by calling various layout procedures after creating the 
items to be laid out. If an item is not explicitly laid out, it will not appear in the form 
window at all. A DefauitLayout procedure is provided that places each created item on a 
separate line. 

A form window consists of horizontal lines with zero or more items on each line. Each line 
may be a different height. Any desired vertical spacing may be accomplished by using 
appropriate heights for lines. Any desired horizontal spacing may be accomplished by 
using appropriate margins between items. Items may be lined up horizontally by using 
TabStops. Lines are created by calling AppendLine or InsertLine. Items are placed on a 
line by calling Appendltem or Insertltem. (See §26.2.6 for more detail.) 
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26.2 Interface Items 



26.2.1 Creating a Form Window, etc. 

Create: proceoure[ 

window: window.Handle, 
makeitemsProc: MakeitemsProc, 
layoutProc: LayoutProc<-NiL. 
windowChangeProc: GlobaiChangeProc nil, 
minDimsChangeProc: MinOimsChangeProc «-niu 
zone: uncounted zone nil, 
clientOata: long pointer nil ]; 

Create takes an ordinary window and makes it a form window. 

window is a window created by tiie client. Windows are usually created by calling 
StarWindowSheil.CreateBody; 

makeitems is a client-supplied procedure that is called to make the form items in the 
window, makeitems should call various FormWindow.MakeXXXitem procedures (see 
§26.2.2). Fine point: makeitems is not called after Create returns, so makeitems can be a nested procedure. 

layoutProc is a client-supplied procedure that is called to specify the desired position of the 
items in the window. layoutProc is called after makeitems has been called. layoutProc 
calls various layout procedures (see §26.2.6), such as AppendLine and Appendltem. If the 
default is taken, the OefauitLayout of one item per line will be used 

windowChangeProc is the global change proc for the entire window Any time any item 
in the window changes, this procedure is called. 

zone is the zone from which storage for the items will be allocated. Form Window uses a 
private zone if none is supplied. 

clientData is passed to makeitems, layoutProc, and windowChangeProc when called. 
May raise ErrorfalreadyAFormWindow]. 

OefauitLayout: LayoutProc; 

The default for the Create layoutProc parameter. Specifies a layout of one item per line. 
Destroy: procedure [window: window.Handte]; 

Destroy destroys all FormWindow data associated with window, turning it back into an 
ordinary window. All form items are destroyed, but the window itself is not destroyed. 
May raise Error[notAFormWlndow]. 

GeKiientOata: procedure [window: window.Handle] 
returns [clientData: long pointer]; 

GetClientData returns the clientData that was passed to Create. May raise 
Error[notAForm Wi ndow] . 

GlobaiChangeProc: type » procedure [ 
window: window.Handie, 
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item: Item Key, 

calledBecauseOf : ChangeReason, 
clientData: long pointer]; 

The client may supply a GiobalChangeProc to Create. Any time the value of any item in 
the window is changed, the GiobalChangeProc is called with the key of the item that was 
changed. If more than one item was changed at one time (such as by a client call to 
FormWindow.Restore), nullltemKey is passed in and the client must examine the "changed" 
boolean of all items to see what was changed (see §26.2.4). calledBecauseOf indicates 
what kind of action caused the GiobalChangeProc to be called. clientOata is the long 
POINTER that was passed to Create. 

GetGlobaiChangeProc: procedure [window: window.Handle] 
RETURNS [proc: GiobalChangeProc]; 

GetGlobaiChangeProc returns the GiobalChangeProc that was passed to Create. May 
raise Error[notAFormWindowI. 

# 

SetGlobalChangeProc: procedure [window: window.Handle, 
proc: GiobalChangeProc] returns [old: GiobalChangeProc]; 

SetGlobalChangeProc changes the GiobalChangeProc that was passed to Create. May 
raise Error[notAForm Window]. 

MinOimsChangeProc: type « procedure [window: window.Handle, 
old, new: window.Dims]; 

Whenever the minimum dimensions of the FormWindow change, the client-supplied 
MinOimsChangeProc is called. This is useful for form windows that are nested as window 
items inside another outer form window. Whenever the dimensions of the nested form 
window change (because of items being made visible or invisible or a te.xt item growing or 
shrinking or new items being added, for example), the client that created the window item 
and the nested form window can be called so that it can make the window item bigger or 
smaller for the nested form window to be completely visible. (See also NeededOims.) 

SetMinOimsChangeProc: procedure [window: window.Handle, 
proc: MinOimsChangeProc] returns [old: MinOimsChangeProc]; 

SetMinOimsChangeProc changes the MinOimsChangeProc that was passed to Create. May 
raise Error [notAFormWindow]. SetMinOimsChangeProc is defined in 
Form WindowExtra2. mesa. 

GetZone: procedure [window: window.Handle] 
returns [zone: uncounted zone]; 

GetZone returns the zone associated with the FormWindow. May raise 
Error[notAForm Wi ndow] . 

Isit: procedure [window: window.Handle] returns [yes: boolean]; 

Isit determines if a window is a form window. If window was made into a form window by 
calling FormWindow.Create, then IsJt returns TRUE, else FALSE. 
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LayoutProc:TYPE ■ procedure [window: window.Handle, clientData: long pointer]; 

The client supplies a LayoutProc to Create to specify the location of items created by the 
MakeltemsProc. See §26.2.6 for details of layout. 

MakeitemsProc: type » procedure [ 
window: window.Handie, 
ciientOata: long pointer]; 

The client supplies a MakeltemsProc to Create to make the form items in the window. 
Create calls the client's MakeltemsProc and various MakeXXXItem procedures (see 
§26.2.2) to make the items, window should be passed to the various MakeXXXItem. 
ciientData is the same as that passed to Create. Fine pointfor clients of Property sheet: dientData can 
be passed to PropertySheet.Create and will be passed on to FormWindow.Create and the MakeitemsProc. 

NeededDims: procedure [window: window.Handle] 
returns [window. Dims]; 

NeededOims returns the minimum dimensions required for a window to hold all the 
currently visible items in the form. 

NumberOfltems: procedure [window: window.Handle] returns [cardinal]; 

NumberOfltems returns the current number of form items in window. This count 
includes visible and invisible items. It is useful for clients that create additional items 
dynamically after the form has been created. May raise Error( notAFormWindowj. 

Repaint: procedure [window: window.Handle]; 

.Repaint causes a window.Vaiidate on window. This is used in conjunction with the 
SetXXXItemValue, SetVisibility, Appendltem, and Insertltem procedures. All these 
procedures take a repaint: boolean parameter. To minimize screen flashing while 
changing several items at the same time, the client may call these procedures with repaint 
■ false and then call FormWindow. Repaint. The form window is not repainted until Repaint 
is called. Warning: After calling any procedure with repaint ■ false, Form window. Re paint 
must be called. Otherwise, the screen will be inconsistent with the internal values. May 
raise Error[notAFormWindow]. 



26.2.2 Making Form Items, etc. 

Create procedures are provided for each type of item. These MakeXXXItem routines are 
used to originally create items in a form window as well as to add items to an existing 
window. 

A number of parameters to each MakeXXXItem procedure are identical and are described 
here, rather than with each procedure. If all of the defaults are taken for an item, it is 
boxed, with no tags and not read-only. All of these may raise Error[notAFormWindow]; 

window is the form window the item is contained in. It should be the same as the window 
passed to the client's MakeltemsProc. 
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myKey is a client-defined key (ItemKey) for the item. The item key uniquely identifies the 
item. It should be used to make calls on other FormWindow procedures, such as 
GetXXXitemValue. Caution: The key must be unique within this form window. 

tag is the text to be displayed before (to the left of) the item on the same line. (To put a tag 
on a separate line, use MakeTagOnlyltem.) 

suffix is the text to be displayed after (to the right of) the item on the same line. 

visibility indicates whether the item should be displayed on the screen. 

boxed indicates whether the item should have a box drawn around it or not. 

readonly ■ true indicates that the user cannot edit the item. The item can be changed by 
calling a SetXXXItemValue procedure. 

ItemKey: type * cardinal; 

ItemKey uniquely identifies an item. An ItemKey is supplied by the client whenever an 
item is made (MakeXXXItem). It should be used thereafter to identify the item to 
FormWindow, such as then calling GetXXXitemValue or SetVisibility. 

Itemlype: type ■ machine dependent {choice(O), multiplechoice, decimal, integer, 
boolean, text, command, tagonly, window, last(15)}; 

There are several types of items, each of which serves a different purpose and behaves 
differently for the user. All items except tagonly and command have a current value that 
can be obtained (GetXXXitemValue) and set (SetXXXItemValue). 

A choice item has an enumerated list of choices, only one of which can be selected at any 
point in time. A choice item's value is of type FormWindow.Choicelndex. 

A multiplechoice item is a choice item that can have an initial value of more than one 
choice selected, but any succeeding values can have only one choice .selected. A multiple 
choice item's value is of type long descriptor for array of cardinal. 

A text item is a user-editable text string, and contains only nonattributed text. A text 
item's value is of type xstring.ReaderBody. 

A decimal item is a text item that has a value of type XLReai.Number. 
An integer item is a text item that has a value of type long integer. 

A boolean item is an item with two states (on and off, or TRUE and FALSE). A boolean 
item's value is of type boolean. 

A command item allows a user to invoke a command. When the user clicks over a 
command item, a client procedure is called. 

A tagonly item is an uneditable, nonselectable text string, 

A window item is a window that is a child of the FormWindow and can contain whatever 
the client desires. A window item's value is a window.Handle. A client must provide its own 
tip. Notify Proc and window display procedure for the window item. 

nullltemKey: ItemKey; 

nullltemKey is used to indicate no item. 
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26.2.2.1 Boolean Items 



MakeBooieanitem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring. Reader <- nil, 
suffix: xstring. Reader «-nil, 
visibility: Visibility «- visible, 
boxed: boolean ^true, 
readonly: boolean «- false, 
changeProc: BooleanChangeProc «~ nil, 
label: BooleanitemLabel, 
initBoolean: boolean <- true); 



MakeBooieanitem creates a boolean item. A boolean item value is of type boolean. When 
the value is true, the item is highlighted. When false, it is not highlighted. When the user 
clicks over the label part of a boolean item, the value toggles. 



Tag 



LABEL 



suffix 



Unhighlighted boolean item, value « FALSE 



changeProc is a client-supplied procedure that is called whenever the value of the item 
changes. 

label is the string or bitmap that the user points at to toggle the item's value. If label is u 
string, the string is copied. If label is a bitmap, the bits are not copied, so the client must 
ensure that the bitmap pointer is valid for the lifetime of the form window. 

initBoolean is the initial value of the item. 

May raise Error[notAForm Window, duplicateitemKey]. 

BooleanitemLabel: TYPE ■ record [ 

var: select type: BooleanitemLabelType from 
string « > [ string: xstring. ReaderBody], 
bitmap ■ > [ bitmap: Bitmap] 
enocase]; 



BooleanltemLabelType: type ■ {string, bitmap}; 

A BooleanitemLabel is passed to MakeBooieanitem. It is the part of the item that the user 
points at and is or is not highlighted, depending on the value of the item. A label may be 
either a string or a bitmap. (See §26.2.8 on Miscellaneous TYPEs for the definition of 
Bitmap.) If label is a string, the string is copied. If label is a bitmap, the bits are not copied, 
so the client must ensure that the bitmap pointer is valid for the lifetime of the form 
window. 

BooleanChangeProc: type ■ procedure [ 
window: window.Handle, 
item: ItemKey, 
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calledBecauseOf : ChangeReason, 
newValue: boolean]; 

The client may provide a BooieanChangeProc to MakeBooleanltem. Whenever the item's 
value changes (TRUE to FALSE or false to true), this procedure is called, window is the form 
window that the item is in. item is the key of the boolean item to which this 
BooieanChangeProc is attached. calledBecauseOf indicates what kind of action caused the 
change procedure to be called. newVaiue is the new value of the item. The item will 
already have the new value when this procedure is called. 

Caution: If a BooieanChangeProc does a SetXXXitem Value, the client should take 
extreme care to prevent infinite recursion. (See §26.3.1.) 

26.2.2.2 Choice Items 

MakeChoiceltem: procedure [ 
window: window. Handle, 
myKey: ItemKey, 
tag: xstring.Reader *- nil, 
suffix: xstring.Reader ^il, 
visibility: Visibility <- visible, 
boxed: boolean*- true, 
readonly: BOOLEAN 4-FALSE, 
values: Choiceltems, 
initChoice: Choiceindex, 
fullyOisplayed: BOOLEAN 4- TRUE, 
verticailyOisplayed: boolean 4- false, 
hintsProc: ChoiceHintsProc4-NiL, 
changeProc: ChoiceChangeProc <- nil, 
outlineOrHighlight: OutlineOrHighlight <- highlight]; 

MakeChoiceltem creates a choice item. A choice item is an enumerated list of choices, only 
one of which can be selected at any time . The choices can be displayed to the user as either 
strings or bitmaps, or some of each. The current choice is highlighted. When the user 
clicks on a choice, it becomes the current choice and is highlighted. Each choice has a 
client-defined Choiceindex associated with it that uniquely identifies that choice. The 
value of a choice item is of type Choiceindex. 

values is the list of all the possible choices. To indicate where to wrap the display around 
to the next line, specify a wraplndicator variant in the appropriate place in the values 
array. If a choice is a string, the string is copied. If a choice is a bitmap, the bits are not 
copied, so the client must ensure that the bitmap pointer is valid for the lifetime of the 
form window. 

initChoice is the value of the initial choice. 

fuliyOisplayed indicates whether all the choices should be displayed or not. If 
fuiiyOisplayed a true, all the choices are displayed. If fultyDisplayed » false, only the 
current choice is displayed, with the rest of the choices being accessed via a pop-up menu 
Caution: bitmaps cannot appear in pop-up menus, so fuliyOisplayed ■ false should not be 
used if the choices are bitmaps. 
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verticailyOisplayed indicates whether the choices should be displayed vertically or 
horizontally. If fuliyDispiayed a false, the value of verticaliyOisplayed is ignored. Any 
wrapindicators are skipped over when choices are displayed vertically. 

If hintsProc is supplied, it is called to make a pop-up hint menu. If the default is taken, the 
form window will make a hint menu with all choices. Note: Because menus can only 
contain strings (not bitmaps), a bitmap choice appears in the hints menu as a number 
indicating the choice's position. Note: This is not the same as the Choicelndex for that 
choice. 

If changeProc is supplied, it is called whenever the choice changes. 

May raise Error[notAFormWindow,dupiicateitemKey, InvalidChoiceNumber]. 

OutiineOrHighlight: type ■ {outline, highlight}; 

Normally, the selected choice for a choice item is indicated by highlighting the choice. The 
OutiineOrHighlight parameter allows the selected choice to be outlined in a black box. 
This is intended to support the Shading choice item on, for example, the triangle and 
ellipse property sheets in the ViewPoint editor. 

Choiceitems: type « long descriptor for array Choicelndex OFChoiceltem; 

Choiceltems is the list of possible choice for a choice item. A, Choiceitems array is passed to 
MakeChoiceitem. The choices are displayed in the order they appear in the Choiceitems 

ARRAY. 

Choiceltem: TYPE « RECORD ( 

var: select type: ChoiceitemType from 
string » > [ 

choiceNumber: Choicelndex, 

string: xstring.ReaderBody], 
bitmap • >[ 

choiceNumber: Choicelndex, 

bitmap: Bitmap], 
wrapindicator ■ > null]; 

ChoiceitemType: type « {string, bitmap, wraplndicator}; 

Choiceindex: TYPE « cardinal [ 0..37777B ]; 

A choice item consists of an array of choices (Choiceitems). Each choice (Choiceltem) 
consists of a unique number that identifies the choice (Choicelndex) and either a string or 
a bitmap to display to the user. In addition, the Choiceitems array can contain a 
wrapindicator wherever the client wants the choices to be wrapped around to begin 
another line of choices. A wrapindicator Choiceltem is not a real choice; it serves only as 
additional layout information for the FormWindow. If Choiceltem is a string, the string is 
copied. If Choiceltem is a bitmap, the bits are not copied, so the client must ensure that the 
bitmap pointer is valid for the lifetime of the FormWindow. 

The client must construct a Choiceitems array before calling MakeChoiceitem. This can 
be simplified if all the choices are strings by using the FormWindowMessageParse 
interface. It allows all the choices for a choice item to be stored as a single XMessage with 
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embedded syntax indicating individual choice strings and choice numbers. (See 
FormWindowMessageParse for more detail.) 

ChoiceChangeProc: type ■ procedure [ 
window: window.Handte, 
item: ItemKey, 

caiiedBecauseOf: ChangeReason, 
oidVaiue, newValue: Choicelndex]; 

The client may provide a ChoiceChangeProc to MakeChoiceitem. Whenever the choice 
changes, this procedure is called, window is the form window that the item is in. item is 
the key of the choice item to which this ChoiceChangeProc is attached. caiiedBecauseOf 
indicates what kind of action caused the change procedure to be called. oldValue and 
newValue correspond to the choice numbers assigned to the choices in MakeChoiceitem 
The item has the new value when this procedure is called. 

Caution: If a ChoiceChangeProc does a SetXXXI tern Value, the client should take extreme 
care to prevent infinite recursion. See §26.3. 1 , Calling ChangeProcs. 

ChoiceHintsProc: type « procedure [ 
window: window.Handle, 
item: ItemKey] 
RETURNS [ 

hints: long descriptor for array of Choicelndex. 
freeHints: FreeChoiceHintsProcl; 

FreeChoiceHintsProc: type ■ procedure [ 
window: window.Handle, 
item: ItemKey, 

hints: long descriptor for array of Choiceindex]; 

The client may provide a ChoiceHintsProc to MakeChoiceitem. Whenever the user points 
at the mouse menu for a choice item, this procedure is called. The hints returned are used 
to construct a pop-up menu that is displayed. If the user selects one of the choices from the 
pop-up menu, that choice becomes the current choice. 

window is the form window that the item is in. 

item is the key of the choice item to which this ChoiceHintsProc is attached. 

hints is an array of choice numbers for the choices that the client wants to appear in the 
menu. This allows a client to show a subset of all the choices to the user for situations in 
which not all the choices make sense, hints must be allocated by the client. 

freeHints is a procedure that is called after the hint menu has been taken down to allow 
the client to free any storage that was allocated when creating the hints array. 

MakeMuitipleChoiceltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstnng. Reader «- nil, 
suffix: xstring. Reader 4-nil, 
visibility: Visibility <- visible, 
boxed : boolean *- true. 
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readonly: boolean «- false, 
values: Choiceitems, 

initCholce: long descriptor for array of Choicelndex, 
verticallyDisplayed: boolean 4- false, 
hintsProc: ChoiceHintsProc <-nil, 
changeProc: MultipleChoiceChangeProc 4>nil]; 

May raise Error[notAForm Window, duplicateltemKey]. 

MultipleChoiceChangeProc: type ■ procedure [ 
window: window.Handle, 
item: Item Key, 

caiiedBecauseOf : ChangeReason, 

oldValue: long descriptor for array of Choicelndex, 

newValue: long descriptor for array of Choicelndex]; 



A multiple choice item is identical to a choice item, except that it may have more than one 
initial value. (See MakeChoiceltem above for details of choice items.) A multiple choice 
item is useful for showing the properties of a heterogenous selection, such as the font 
property of a text selection that has more than one font. 



26.2.2.3 Command Items 



MakeCommandltem: procedure [ 

window: window. Handle, .0^^ 

myKey: ItemKey, 

tag: xstring.Reader «- nil, 

suffix: xstring.Reader «-nil, 

visibility: Visibility <- visible, 

boxed: boolean true, 

readonly: boolean false, 

commandProc: CommandProc, 

commandName: xstring.Reader, 

ciientOata: long pointers- nil]; 



Creates a command item. A command item allows a user to invoke a command. When the 
user clicks over the commandName, commandProc is called, [f boxed is true, the 
commandName appears with a rounded corner box drawn around it (rather than a square- 
cornered box, to distinguish a command item from a boolean item). May raise 
Error[notAForm Wi ndow, du pi i cateltem Key ] . 



NewMakeCommandltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader <- nil, 
suffix: xstring.Reader ^nil, 
visibility: Visibility visible, 
boxed: boolean true, 
readonly: boolean^ false, 
commandProc: CommandProc, 
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label: CommandltemLabei, 
clientOata: long pointers- nil]; 

CommanditemLabel: TYPE ■ record [ 

var: select type: CommandltemLabeiType from 
string ■ > [string: xstring.ReaderBody], 
bitmap ■ > [bitmap: Bitmap], 
endcase]; 

CommandltemLabeiType: TYPE « {string, bitmap}; 

NewMakeCommandltem is just like MakeCommandltem, but allows the label to be a 
.bitmap. If label is the bitmap variant, the client must leave the storage for the bitmap 
allocated as long as the item exists. NewMakeCommandltem is defined in 
Form Window E xtra3 . mesa. 

CommandProc: type » procedure [ 
window: window.Handle, 
item:ltemKey, clientOata: long pointer]; 

A CommandProc is supplied by the client to MakeCommandltem. It is called whenever 
the user selects the command item, window is the Form Window that the item is in. item 
is the key of the command item to which this CommandProc is attached. 

26.2.2.4 Tagonly items 

MakeTagOnlyitem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader, 
visibility: Visibility visible]; 

Creates a tagonly item. Tagonly items are displayed as uneditable, nonselectable text. 
May raise Error(notAForm Window, duplicateltemKey]. 

26.2.2.5 Text and Number Items 

MakeTextltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader <- nil, 
suffix: xstring.Reader 4- NIL, 
visibility: Visibility <- visible, 
boxed : boolean «- tru e , 
readonly: boolean false, 
width: CARDINAL, " in screen dots 
initString: xstring.Reader*- nil, 
wrapUnderTag: boolean «- false, 
passwordFeedback : boolean *~ false, 
hintsProc: TextHintsProc4-NiL, 
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nextOutOf Proc: NextOutOf Proc <- nil, 
SPECiALKey board: BiackKeys.Key board nil] ; 

Creates a text item. Text items are user-editable text strings. The value of a text item is of 
type xstring.ReaderBody. The user may select text, extend the selection, insert text, delete 
text, move and copy text.and so forth. Text items are fixed width but may grow and shrink 
vertically as the user enters and deletes text. A text item contains nonattributed text only. 
FormWindow handles all storage allocation for the backing string. 

width is the number of screen dots wide that the item should be. The item may grow 
arbitrarily long as the user enters text, but it will always retain the same width. 

initString is the initial string to place in the text item. The bytes are copied by 
FormWindow. 

wrapUnderTag specifies whether any text wider than the width of the text item should 
appear underneath the tag (wrapUnderTag a true) or start at the left edge of the text 
item (wrapUnderTag ■ false). Note: This feature is not yet implemented: items always 
behave with wrapUnderTag ■ false. 

passwordFeedback indicates that the text should be displayed in an unreadable form 
(such as asterisks) rather than as normal characters. The correct value of the string is 
maintained internally, so that a call to GetTextltem Value will return the proper value. If 
any part of a passwordFeedback field is copied or moved, the underlying string is NOT 
copied. 

If hintsProc is supplied, it is called to make a list of strings to be displayed to the user as a 
pop-up hint menu. (See TextHintsProc below.) 

If nextOutOfProc is supplied, it is called when the user presses the NEXT key while the 
input focus is in this text item. This gives the client an opportunity to create more text 
items. After calling the nextOutOfProc or if no nextOutOfProc is supplied, the NEXT key 
causes the selection and input focus to move to the next text or window item in the form. 
See NEXT key in this chapter for further explanation. 

If SPECiALKeyboard is supplied, it allows clients to make a special keyboard available to 
the user when typing into a text or number field. 

May raise Error[notAForm Window, duplicateltemKey]. 

MakeDecimalltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader 4-nil, 
suffix: xstring.Reader 4-NiL, 
visibility: Visibility <- visible, 
boxed: boolean 4- true, 
readonly: BOOLEAN <- FALSE, 
signed: boolean <- false, 
width: CARDINAL, — in screen dots — 
initDecimal: XLReai. Number 4- XLReaLzero, 
wrapUnderTag: boolean 4-FALSE, 
hintsProc: TextHintsProc ♦-nil, 
nextOutOfProc: NextOutOfProc <- nil. 
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dispiayTempiate: xstring. Reader <- nil. 
SPECIALKey board : BiackKeys.Key board <~ nil]; 

Creates a decimal item. A decimal item is a text item that has a value of type 
XLReai.Number. (See MakeTextltem above for details of text items.) The user can type any 
text into the decimal item, but when the client calls GetOecimailtemVaiue to retrieve the 
value, FormWindow converts the string to XLReai.Number. initOecimal is the initial 
decimal value to place in the item. dispiayTempiate parameter is defined as in the 
XLReal.PictureReal. XLReai.PtctureReal displays the value of the decimal item. The client 
may provide a keyboard interpretation with the SPECIALKeyboard parameter (see 
Chapter §9.2.1 ). May raise ErrorCnotAForm Window, duplicateitemKey]. 

Makeintegerltem: procedure [ 
window: window.Handle, 
myKey: ItemKey, 
tag: xstnng. Reader <- nil, 
suffix: xstring.Reader<--NiL, 
visibility: Visibility ^visible, 
boxed : boolean «- true, 
readonly : boolean *- false, 
signed: boolean false, 
width: cardinal, — in screen dots •- 
initlnteger: long integer *- 0, 
wrapUnderTag: boolean*- false, 
hintsProc: TextHlntsProc«-NiL, 
nextOutOf Proc: NextOutOfProc «- nil, 
SPECIALKeyboard: BiackKeys.Keyboard <- nil ]; 

Creates an integer item. An integer item is a text item that has a value of type long 
INTEGER. (See MakeTextltem above for details of text items.) The user can type any text 
into the integer item, but when the client calls GetlntegerltemValue to retrieve the value, 
FormWindow converts the string to a LONG INTEGER, initlnteger is the initial number to 
place in the item. The client may provide a keyboard interpretation with the 
SPECIALKeyboard parameter (see §9.2.1). May raise Error[ notAFormWindow, 
duplicateitemKey]. 

TextHintAction: TYPE ■ {replace, append, nil}; 

TextHintsProc: type a procedure ( 
window: window.Handle, 
item: ItemKey] 
returns [ 

hints: long descriptor for array of xstring.ReaderBody, 
freeHints: FreeTextHintsProc, 
hintAction: TextHintAction replace]; 

FreeTextHintsProc: type « procedure [ 
window: window.Handle, 
item: ItemKey, 

hints: long descriptor for array of xstring.ReaderBody]; 
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The client may provide a TextHintsProc to MakeTextltem, MakeDecimalltem, and 
Makelntegerltem. Whenever the user points at the mouse menu for a text item, this 
procedure is called. The hints returned are used to construct a pop-up menu that is 
displayed. 

When the user selects one of the strings from the pop-up menu, one of three things happen, 
depending on the hintAction returned by the TextHintsProc. If hintAction « replace, the 
selected string replaces the current value of the text item. If hintAction ■ append, the 
selected string is appended to the current value of the text item. If hintAction ■ nil. the 
current value of the text item does not change hintAction « nil is useful for displaying 
"help-like" information to the user for text items that do not have a finite number of 
possible values, such as a file name. 

freeHints is a procedure that is called after the hint menu has been taken down to allow 
the client to free any storage that was allocated when creating the hints array. 



26.2.2.6 Window Items 

MakeWindowltem: PROCEDURE I 
window: window.Handle, 
myKey: ItemKey, 
tag: xstring.Reader <- nil, 
visibility: Visibility <- visible, 
boxed: boolean true, 
size: Window. Dims, 
nextintoProc: NextlntoProc 4-nil] 
RETURNS [clientWindow: window.Handle]; 



Creates a window item. A window item is a window (window.Handle) that is a child of the 
FormWindow. It can contain anything the client desires. A window with dimensions size 
is created and returned as clientWindow. It is expected that the client will associate a 
display procedure (see window.SetDisplayProc) and a TiP.NotifyProc with the window. The 
window may be treated just like any other window, except FormWindow.SetWindowltemSize 
must be used to change the size of the window rather than calling window. SlideAndSize 
directly. This allows FormWindow to move any other items, if necessary, to accommodate 
the different-sized window item. 

If nextintoProc is supplied, it is called when the user presses the NEXT key in an item just 
before this window item. This gives the window item an opportunity to gain control of the 
NEXT key by setting the input focus to be the window item's window. The window item 
may then retain control of the .NEXT key within the window item. When the window item 
no longer wants to process the NEXT key (for instance, when the NEXT key should move the 
selection outside the window item), the window item client must call 
FormWindow.TakeNEXTKey, which returns the next key processing to the form window. 
(See §26.2.10 for an explanation of the NEXT key.) 

May raise Error[notAForm Window, duplicateitemKey]. 



SetWindowitemSize: procedure [ 
window: Window.Handle, 
windowltemKey: ItemKey, 
newSize: window. Dims]; 
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SetWindowitemSizeExtra: procedure [ 
window: Window. Handle, 
windowltemKey: ItemKey, 
newSize: window.Oims, 
repaint: boolean <~ true]; 

SetWindowitemSize (or SetWindowitemSizeExtra) is used to change the size of a window 
item's window. The client should never call window.StideAndSize directly. Any items 
below the window item are moved down or up to accommodate the new dimensions, 
window is the form window that the window item is in; windowltemKey must be the key 
of a window item. newSize indicates the new dimensions. SetWindowitemSizeExtra is 
defined in FormWindowExtra.mesa. May raise Error[ notAFormWindow, 
invalidltemKey, wrongltemType]. 

26.2.2.7 Destroying Items 

Oestroyltem: procedure [ 
window:window.Handle, 
item: ItemKey, 
repaint: boolean true]; 

Destroyltem destroys item. Most clients do not need to use this procedure, because 
FormWindow. Destroy destroys all the items in the FormWindow. May raise 
Error[notAFormWindow, invaliditemKey]. 

Oestroyitems: procedure [ 
window:window.Handle, 
item: long descriptor for array of ItemKey, 
repaint: boolean «-true]; 

Oestroyitems destroys several items at once. Most clients do not need to use this 
procedure, because FormWindow. Destroy destroys all the items in the FormWindow. May 
raise Error[notAForm Window, invaliditemKey]. 

26.2.3 Getting and Setting Values 

The client may examine or change the value of an item. All GetXXXItem procedures 
return the current value of an item. All SetXXXItem procedures take a given new value 
and change the value internally, as well as updating the screen if necessary. 

In all these procedures, window is the FormWindow the item is in. item uniquely 
identifies the item to get or set the value of. 

Note: There are two ways to get the value of a text item. GetTextltem Value copies the 
bytes of the string so that the client owns the storage for the returned value 
LookAtTextltemValue simply returns a pointer to the FormWindow-owned backing 
string. This value is therefore read-only and must be released when the client has finished 
examining it by calling OoneLookingAtTextitemValue. 

All of these may raise Errorf notAFormWindow, invaliditemKey, wrongltemType]. 
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26.2.3.1 Getting Values 

GetBooieanitemVaiue: PROCEDURE [ 
window: window.Handle, 
item: ItemKey] 
RETURNS [value: boolean]; 

GetChoiceltemValue: procedure [ 
window:window.Handle, 
item: ItemKey] 
returns [value: Choiceindex]; 

GetDecimailtemValue: procedure [ 
window: window.Handie, 
item: ItemKey] 

returns [value:xLReai.Number]; 

May raise XLRaai.Error [notANumber]. 

GetlntegeritemValue: procedure [ 
window: window.Handle, 
item: ItemKey] 
returns [value: long integer]; 

May raise xstring.invalidNumber or XString.Overflow. 

GetMultipleChoiceltemValue: procedure [ 
window:window.Handle, 
item: ItemKey, zone: uncounted zone] 
returns [values: long descriptor for array of Choiceindex]; 

The zone parameter is added. The storage for the DESCRIPTOR is allocated out of zone and 
the storage must be freed by the client. 

GetTextltem Value: procedure [ 
window: window.Handle, 
item: ItemKey, 
zone: uncounted zone] 
returns [value: xstring.ReaderBody]; 

GetTextltem Value copies the string. Storage for the bytes is allocated out of zone. The 
client should free the storage using xstring.FreeReaderBytes and zone. 

GetWinddwItemValue: procedure [ 
window: window.Handle, 
item: ItemKey] 

- returns [value: window.Handle]; 

LookAtTextltemValue: procedure [ 
window: window.Handle, 
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item: itemKey] 

RETURNS [value: xstring.ReaderBody]; 

DoneLookingAtTextltemValue: procedure [ 
window: window.Handie, 
item: ItemKey]; 

LookAtTextltemValue does not copy the string but returns a pointer to it. The client 
should not change value. Clients using LookAtTextltemValue must call 
DoneLookingAtTextltemValue when through examining it. During the time between 
these calls, if another client calls LookAtTextltemValue or SetTextltem Value for the same 
text item, the second client's process waits. 

GetNextAvailableKey: procedure [window: window.Handle] 
RETURNS [key: ItemKey] ; 

Returns the next available item key: MAX[usedKeys| + I. 

26.2.3.2 Setting Values 

All the SetXXXItem procedures take a repaint: boolean. If repaint ■ true and the item is 
currently visible, it is repainted with the new value. If repaint ■ false, the item is not 
repainted until FormWindow. Re paint is called. This allows the client to change the values of 
several items at once without the screen flashing for each item. Warning: After calling 
any procedure with repaint ■ false, FormWindow.Repaint must be called. Otherwise, the 
screen will be inconsistent with the internal values. 

Caution: If a change procedure does a SetXXXItem Value, the client should take extreme 
care to prevent infinite recursion. (See §26.3.1.) 

SetBooleanltemValue: procedure [ 
window: window.Handle, 
item: ItemKey, 
newValue: boolean. 
repaint: boolean 4-true]; 

SetChoiceltemValue: procedure [ 
window: window.Handle, 
item: ItemKey, 
newValue: Choicelndex, 
repaint: boolean *-true]; 

May raise FormWindow.Error[invalidChoiceNumber]. 

SetDecimalltem Value: procedure [ 
window: window.Handle, 
item: ItemKey, 
newValue: xLReal.Number, 
repaint: boolean «--true]; 

SetlntegerltemValue: procedure [ 
window: window.Handle, 
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item: ItemKey, 
newVaiue: long integer, 
repaint: boolean 4-true] ; 

SetMultipieChoiceitem Value: procedure [ 
window:window.Handie, 
item: ItemKey, 

newValue: long descriptor for array of Choicelndex, 
repaint: boolean 4-true] ; 

May raise FormWindow.Error[invalidChoiceNumber]. 

SetTextitemValue: procedure [ 
window: window.Handle, 
item: ItemKey, 
newValue: xstrmg.Reader, 
repaint: boolean 4-true]; 

26.2.4 "Changed" BOOLEAN 

Every item that has a value that the user can change (except tagonly and command items) 
has a "changed" boolean associated with it. All items are created with this boolean set to 
false. FormWindow automatically sets this boolean to true whenever the user changes the 
item or when a client calls one of the SetXXXItemValue procedures. This allows the client 
to determine which items have changed when, for example, the user selects Done or Apply 
on a property sheet. The client is responsible for resetting the changed boolean to false by 
calling ResetChanged or ResetAIIChanged after examining the changed boolean with 
HasBeenChanged or HasAnyBeenChanged. 

HasAnyBeenChanged: procedure [ 
window: Window.Handle] 
RETURNS [yes: boolean]; 

HasAnyBeenChanged returns true if any item's changed boolean is true. May raise 
Error[notAFormWindow]. 

HasBeenChanged: procedure [ 
window: window.Handle, 
item: ItemKey] 
RETURNS [yes : boolean] ; 

HasBeenChanged returns true if the user has changed item. The client may reset the 
changed boolean to false by using ResetChanged or ResetAIIChanged. If item is tagonly or 
command, HasBeenChanged returns false. May raise Error[notAFormWindow, 
invalidltemKey]. 

ResetChanged: procedure [window: window.Handle, item: ItemKey]; 

ResetChanged sets the changed boolean of item to false. May raise Error[ 
notAForm Window, invalidltemKey]. 



26-20 



ViewPoint Programmer's Manual 



26 



ResetAJIChanged: procedure [window: window.Handie]; 

ResetAIIChanged sets the changed boolean of all items to false. May raise Error[ 
notAFormWindow]. 

SetChanged: procedure [ 
window: window.Handie, 
item: ItemKey]; 

SetChanged sets the changed boolean of item to true. iMay raise Error[ notAFormWindow. 
invalidltemKey]. 

SetAliChanged: procedure [ 
window: window.Handie]; 

SetAliChanged sets the changed boolean of all items to true. May raise .Error{ 
notAFormWindow]. 

26.2.5 Visibility 

Visibility: TYPE ■ {visibleJnvisibleJnvisibleGhost}; 

An item either is or is not displayed in the form window. If an item is displayed in the form 
window, it is visible. If an item is not currently displayed, it is either invisible or 
invisibleGhost. If it is invisible, it does not take up any space on the screen; any items 
below it move up to take its screen space. If an item is invisibleGhost, the space that it 
would occupy were it visible is white on the screen. An item's visibility can be changed 
anytime by calling SetVisibility 

GetVisibility: procedure [ 
window: window.Handie, 
item: ItemKey] 
returns [visibility: Visibility]; 

GetVisibility returns the current visibility of item. May raise Error(notAFormWindow, 
invalidltemKey]. 

SetVisibility: procedure [ 
window: window.Handie, 
item: ItemKey, 
visibility: Visibility, 
repaint: BOOLEAN 4>true]; 

SetVisibility sets the visibility of item. If repaint ■ true and the item's visibility is 
changing, the form window is repainted. If repaint ■ false, the form window is not 
repainted until FormWindow. Repaint is called. This allows the client to change the visibility 
of several items at once without the screen flashing for each item. Warning: After calling 
SetVisibility with repaint « false, FormWindow. Repaint must be called. Otherwise, the 
screen will be inconsistent with internal values. May raise Error[notAForm Window, 
invalidltemKey]. 
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26.2.6 Layout 

Items in a form window are laid out by calling various procedures specified below, after 
creating the items to be laid out. If an item is not explicitly laid out, it does not appear in 
the form window at all. Note: FormWindow.OefaultLayout may be used when the client is 
not concerned with the exact placement of items but wants a functional form window. 

There are two different types of layout. The most common is flexible layout, which allows 
text, decimal, integer, and window items to grow and shrink (and all other items to be 
moved around accordingly) as the user or client changes their values. Flexible layout is 
done by calling such procedures as AppendLine and Appendltem. Fixed layout allows the 
client to specify exactly where items will go by calling SetltemBox but does not allow text, 
decimal, integer, and window items to grow or shrink. All items stay where they are laid 
out unless the client calls SetltemBox again. 

26.2.6.1 Flexible Layout 

A form window with flexible layout consists of horizontal lines with zero or more items on 
each line. Lines are always just tall enough to hold the items on that line. The 
spaceAboveLine parameter specifies the amount of white space to leave above each line. 
Horizontal spacing is accomplished by using appropriate margins between items. Items 
may be lined up horizontally by using TabStops (see §26.2.6.2 below). 

Lines are created by calling AppendLine or InsertLine. Items are placed on a line by jg/tt^ 
calling Appendltem or Insertltem. The Append routines add items after the previously 
created line or item The Insert routines add items between previously created items or 
lines. 

AppendLine: procedure [ 
window: window.Handle, 
spaceAboveLine: cardinal *- 0] 
RETURNS [line: Line]; 

AppendLine creates a new line and appends it to the bottom of the form window. All items 
must be placed on a line, so AppendLine must be called before any calls to Appendltem. 
The line returned by AppendLine should be passed to Appendltem or Insertltem. window 
is the Form Window the line is being appended to. May raise ErrorfnotAFormWindow]. 

Line: type; 

Line uniquely identifies a line and is returned by AppendLine and InsertLine. A Line must 
be passed to Appendltem and Insertltem. 

Appendltem: procedure [ 
window: window.Handle, 
Item: ItemKey, 
line: Line, 

preMargin: cardinal 4-0, 

tabStop: cardinal *- nextlabStop, jHIl 
repaint: BOOLEAN 4-true]; 
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Appendltem appends item to line. 

preMargin is the number of pixels of white space to place before the left edge of this item. 
If tabs have been set, preMargin is added after placing the item at its tab stop. 

tabStop is the ordinal number of the tab stop at which to place this item, [f the default is 
taken, the next tab stop on the line after the previous item is used. If no tabs have been 
defined (if SetTabStops has never been called), tabStop is ignored. (See §26.2.6.2 for more 
detail on tabs.) 

repaint specifies whether the screen should be repainted after the Appendltem is done. 
When called from the client's LayoutProc, repaint is ignored and the items are not painted 
until the LayoutProc returns. When not called from the client's LayoutProc, and repaint = 
TRUi, the form window is repainted immediately after appending the item. When not 
called from the client's LayoutProc, and repaint = false, the form window is not repainted 
until FormWindow. Repaint is called. This allows the client to add several items at once 
without the screen flashing for each new item. Warning: After calling Appendltem with 
repaint = false, FormWindow. Repaint must be called. Otherwise, the screen will be 
inconsistent with internal values. 

May raise Error[notAFormWindow, invaliditemKey, noSuchLine]. 

InsertLine: procedure [ 
window: window.Handle, 
before: Line, 

spaceAboveLine: cardinal 4-0] 
RETURNS [line: Line]; 

InsertLine inserts a new line before (above) an existing line. The spaceAboveLine 
parameter indicates how much space (in screen dots) to leave between the previous line 
and this line. This allows clients to leave white space at the top of the form before the first 
line and also provides an easy way to put white space in a form. (See AppendLlne for 
details of creating a line.) May raise Error{notAFormWindow, noSuchLine]. 

Insertltem: procedure [ 
window: window.Handle, 
item: ItemKey, 
line: Line, 

beforeltem: item Key, 
preMargin: cardinal 4-0, 
tabStop: cardinal «- nextTabStop, 
repaint: BOOLEAN 4-trueI: 

Insertltem inserts item to the left of beforeltem on line. (See Appendltem for details of 
placing an item on a line.) May raise Error [notAFormWindow, InvalidltemKey, 
noSuchLine, itemNotOnLine]. 

RemoveitemFromLine: procedure! 
window: window.Handle, 
item: ItemKey, 
line: Line, 

repaint: boolean true]; 
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Removeitem From Line "unlayouts" an item that has been previously laid out. This allows 
clients to move an item from one place on the form to another without destroying and 
recreating the item, by calling Removeitem From Line followed by a call to Appendltem or 
Insertltem. RemoveltemFromLine does not destroy the item. The item is "in limbo" until it 
is laid out again by using Appendltem or Insertltem. 

LayoutlnfoFromltem: procedure [ 

window: window.Handle, item: ItemKey] 
RETURNS [ line: Line, margin: cardinal, 
tabStop: cardinal, box: window.Box]; 

LayoutlnfoFromltem returns various layout characteristics of item. May raise 
Error[notAForm Window, invalidltemKey]. 

LineUpBoxes: procedure [window: window. Handle, 
items: long descriptor for array of ItemKey nil]; 

Calling this procedure forces the boxes of the specified items to line up vertically, as in 
most ViewPoint property sheets. If no items are specified and a fixed-pitch font is used, the 
first item on every line lines up as shown in Figure 26. 1. 







tagi 


boxed boolean item 








tagOnLine2 


boxed choice item 










boxed text item 










veryLongTagLine4 


boxed boolean item 







Figure 26.1 LineUpBoxes 



The specified items must be the first item on their line. The longest tag is measured: then 
the boxed part of each item appears at the next available tab stop after the longest tag. 
This also works for non-boxed items. 



26.2.6.2 Tabs 

TabType: type * {fixed, vary}; 

TabStops: TYPE ■ record! 

variant: select type: TabType from 

fixed ■ > [interval: cardinal], 

vary « > [list: long descriptor for array of cardinal] 

endcase ]; 
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The client may specify tab stops to facilitate lining up items one directly below the other. 
Tabs may be specified two ways: fixed and varying. Fixed tab stops are specified by a 
single CARDINAL (interval) that indicates a tab stop at each interval pixel. For example, if 
interval = 10, there will be tab stops at 10, 20, 30, and so forth. Varying tab stops are 
specified by an array of cardinal. Each element of the array indicates the number of pixels 
from the left edge of the window. Typically, a client calls SetTabStops at the beginning of 
the LayoutProc and then calls AppendLine and Appendltem repeatedly, taking the 
nextlabStop default for each item. 

noTabStop: CARDINAL ■ caroinallast-I ; 

Can be used with Appendltem and Insertltern to indicate that this item should ignore tab 
stops completely. 

defaultTabStops: TabStops > [fixed(interval: 100]]; 

SetTabStops: procedure [window: window.Handie, tabStops: TabStops); 

SetTabStops sets the tab stops for window. Any items laid out before to this call are 
moved to conform to these tab stops. May raise Error[ notAFormWindow]. 

nextlabStop: cardinal > . . . ; 

Used for item layout, this is the default for the tabStop parameter for Appendltem and 
Insertltem. It indicates that the next item should be placed at the next tab stop. 

GetTabStops: procedure [window: window.Handie] 
RETURNS [tabStops: TabStops] ; 

GetTabStops returns the current tab stops for window. If no tab stops have been set for 
window, tabStops is fixed with an interval of 0. May raise Error[ notAFormWindow]. 

26.2.6.3 Fixed Layout 

SetltemBox: procedure [ 
window: window.Handie, 
item: Item Key, 
box: Window. Box]; 

SetltemBox sets the exact position of an item for fixed layout. With fixed layout, all items 
stay where they are laid out unless the client calls SetltemBox again. With fixed layout, 
text, decimal, integer, and window items do not grow or shrink. SetltemBox is 
incompatible with flexible layout (such as AppendLine, Appendltem, SetTabStops, and so 
forth). Note: Either all layout must be flexible, or all layout must be fixed. Attempting to 
mix them raises Error[notAForm Window, invalldltemKey]. 

26.2.7 Save and Restore 

Restore: procedure [window: window.Handie]; 
Save: procedure [window: window.Handie]; 
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Restore and Save deal with restoration of a form window to a previous state. Save causes 
the current item values to be saved. Restore causes the previously saved values to be 
copied back into the form. A Restore done before a Save is a no-op. Save done after Save 
(but before a Restore) overwrites the first Save. These procedures support the Reset 
function of property sheets. May raise Error[notAFormWindow]. 

26.2.8 Miscellaneous TYPEs 

Bitmap: type « record[ 
height, width: cardinal, 
bitsPerLine: cardinal, 
bits: Environment.BitAddress]; 

A Bitmap is the data structure that is passed to MakeBooieanitem and MakeChoiceltem 
for items that are to be displayed as bitmaps, height is the bitmap's height In pixels, width 
is the bitmap's width in pixels, bits is a pointer to the actual bits in the bitmap. bitsPerLine 
is the number of bits in each line of bits. bitsPerLine is usually greater than or equal to 
width and is often a multiple of 16. 

ChangeReason: TYPE ■ {user, client, restore}; 

A ChangeReason Ls passed to a GiobalChangeProc, BooleanChangeProc, and 
ChoiceChangeProc. It indicates whether the change was caused by the user, by the client 
calling SetXXXItemValue, or by the client calling Restore. 

26.2.9 Miscellaneous Item Operations 



GetReadOnly: procedure [window: window. Handle, item: ItemKey] 
RETURNS [readonly: boolean]; 

GetReadOnly returns the current value of the readonly boolean for item. May raise 
Error[notAForm Window, invaliditemKey]. 

GetTag: procedure [ 

window: window.Handle, 
item: ItemKeyl 
returns [tag: xstring.Reader]; 

GetTag returns the tag associated with item. May raise Error[notAForm Window, 
invaliditemKey]. 

SetSelection: procedure [ 
window: window.Handle, 
item: ItemKey, 
fIrstChar: cardinal 4-0, 
lastChar: cardinal <- caroinal.last]; 



SetSelection sets the current selection to be item. It is useful for helping the user correct 
an incorrect user entry, item must be a text, decimal, or integer item. firstChar is the first 
character of the portion of the string to be selected and highlighted. lastChar is the last 
character of the portion of the string to be selected and highlighted. The defaults for 
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firstChar and iastChar cause the entire string to be selected. May raise 
Error[notAForm Window, invalidltemKey, wrongitemType]. 

SetlnputFocus: procedure [ 
window: window.Handle, 
item: ItemKey, 

beforeChar: cardinal <- cardinallast]; 

SetlnputFocus sets the current input focus to be in item. It is useful for highlighting an 
incorrect user entry, item must be a text, decimal, or integer item. beforeChar is the 
character before which the input focus should go. The default causes the input focus to be 
at the end of the string. May raise Error[notAFormWindow. invaiidltemKey, 
wrongitemType]. 

SetReadOnly: procedure [ 
window: window. Handler 
item: ItemKey, 
readonly: boolean] 
RETURNS [old: boolean]; 

SetReadOnly sets the current "readOnly-ness" of item and returns the old value. May 
raise Error [notAForm Window, invalidltemKey]. 

SetltemWidth: procedure [window: window.Handle, item: ItemKey, 
width: cardinal]; 

This procedure sets the width of an item. Normally, items are as wide as they need to be to 
display the text of the item (except text, decimal, and integer items, whose width is 
specified when the items are created). SetltemWidth overrides the normal width of the 
item and thus could truncate the text of the item. SetltemWidth should therefore be used 
with great caution. In particular, programmers should keep in mind that applications are 
intended to be multilingual, and strings in other languages are often longer than their 
English equivalents. This layout procedure can only be used with a flexible layout. 

SetltemFont: procedure ( 
window: window.Handle, 
item: Item Key, 

newFont: SimpielextFont-MappedFontHandle «-nil, 
repaint: boolean true]; 

SetltemFont changes the font of a text or number item. It does not affect the tag or suffix. 
If newFont is nil, the system font is used. May raise Error[notAForm Window, 
invalidltemKey]. SetltemFont is defined in For mWindowExtra4. mesa. 

SetLosingFocusProc: procedure I 
window: window.Handle, 
item: ItemKey, 
proc: LosingFocusProc]; 

LosingFocusProc: TYPE ■ procedure [window: Window.Handle, item: ItemKey]; 
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SetLosingFocusProc associates proc with item, proc is called whenever item loses the 
input focus, allowing clients to undo things that were done when the input focus was set, 
such as clear some SoftKeys. item must be a text or number item. May raise 
Error[notAForm Window, invalidltemKey]. SetLosingFocusProc and LosingFocusProc are 
defined in FormWindowExtraS.mesa. 

SetTookFocusProc: procedure [window: window.Handle, proc: LosingFocusProc]; 

TookFocusProc: type ■ procedure [window: Window.Handle, item: ItemKey]; 

SetTookFocusProc associates proc with window, proc is called whenever the form 
window takes the input focus, item is the item that took the input focus. It is a text or 
number item. May raise Error[notAForm Window, invalidltemKey]. SetTookFocusProc 
and TookFocusProc are defined in FormWindowExtra6.mesa. 



26.2.10 NEXT Key 

When the user presses the NEXT key while the input focus is in a form window (more 
exactly: in a text, decimal, or integer item in a form window), the form window does the 
following: 

1. If the item with the input focus has a NextOutOfProc, it is called. This gives the client 
an opportunity to, for example, add another blank text item after this one. 

2. Find the next text, decimal, integer, or window item. Note: If the client added another 
text item after the one that had the input focus, that new item is the one found by the 
form window. 

3a. If the next item is a text, decimal, or integer item, the input focus and selection are 
moved to that item. 

3b. If the next item is a window item and the window item has a NextlntoProc, it is called, 
giving the window item an opportunity to take the input focus. For example, if the 
window item contains a table of values, the NEXT key could be used to step from entry 
to entry through the table, but the window item's TiP.NotifyProc would have to do this. 
Note: If a NextlntoProc is supplied for a window item, it must call TiP.SetinputFocus so 
that all further NEXT key notifications go to the window item. When the window item 
no longer wants the NEXT key (such as when the user has NEXTed out of the last entry 
of the table), it must call FormWindow.TakeNEXTKey. TakeNEXTKey proceeds as in steps 
2 and 3. 

3c. If the next item is a window item, but the window item does not have a NextlntoProc, 
the form window repeats steps 2 and 3. 

NextlntoProc: TYPE « PROCEDURE [ 
window: window.Handle, 
item: ItemKey]; 

A NextlntoProc can be provided by the client with window items. If provided, the 
NextlntoProc is called when the user NEXTs into the item using the next key. (See the 
discussion above.) 
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NextOutOfProc: type ■ procedure ( 
window: wfndow.Handie, 
item: ItemKey]; 

A NextOutOfProc can be provided by the client with text, decimal, and integer items. If 
provided, the NextOutOfProc is called when the user presses the NEXT key while the input 
focus is in an item just before this one. (See the discussion £bove.) 

SetNextOutOfProc: procedure [ 
window: window.Handle, 
item: ItemKey, 

nextOutOfProc: NextOutOfProc] 
returns [old: NextOutOfProc]; 

SetNextOutOfProc sets the NextOutOfProc for a text, decimal, or integer item. It is useful 
when the NextOutOfProc for a text item creates another text item after itself. After 
creating the new item, the client will probably want to set the NextOutOfProc for the old 
item to NIL, so that next time the user NEXTs out of the old item, the selection and input 
focus simply move to the new item rather than creating another new item. 

GetNextOutOfProc: procedure [ 
window: window. Handle, 
item: ItemKey] 
RETURNS [NextOutOfProc] ; 

GetNextOutOfProc returns the NextOutOfProc for item. 

TakeNEXTKey: procedure [ 
window: window.Handle, 
item: ItemKey]; 

TakeNEXTKey informs the form window that the window item which was handling the 
NEXT item is done with it and the input focus should be passed on to the next item that can 
take it. item identifies the window item that is involved. May raise 
Error[notAForm Window, wrongltemType]. 

26.2.11 SIGNALS and ERRORS 

Error: error [code: ErrorCode]; 

ErrorCode: type ■ machine dependent {notAFormWindow(O), wrongltemType, 
invalidChoiceNumber, noSuchLine, aireadyAFormWindow, 
invalidltemKey, itemNotOnLine, duplicateltemKey, 
incompatibieLayout, aireadyLaidOut, last(15)}; 

notAForm Window The term notAFormWindow means the window passed in to 

the procedure is not a form window. Any FormWindow 
procedure, except Create and Isit, may raise this error. 

wrongltemType The term wrongltemType means the item passed in to the 

FormWindow procedure is the wrong type. For example, 
GetChoiceltem Value must be passed a choice item. 
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invalidChoiceNumber 
noSuchLine 

alreadyAFormWindow 

invalidltemKey 
itemNotOnLine 

duplicateitemKey 
i ncompati bieLayout 
alreadyLaidOut 



The term invalidChoiceNumber means the choice number 
supplied does not match any of the choice numbers in the 
Choiceltems. 

The term noSuchLine means the line supplied to 
Appendltem or Insertltem was not previously created. 

The term alreadyAFormWindow means the window passed 
in is already a form window. Raised if a ^orm Window is 
passed into Create. 

The term invalidltemKey means an ItemKey was used for 
which there was no item created. 

The term itemNotOnLine means an attempt was made to 
insert an item on a line before an item that is not on that 
line. (See Insertltem.) 

The term duplicateitemKey means an item was created with 
the key of another item. ItemKeys must be unique. 

The term incompatibleLayout means the client is 
attempting to intermix fixed and fle.xible layout styles. 

The term alreadyLaidOut means an attempt was made to 
specify the layout for an item more than once. 



LayoutError: signal [code: LayoutErrorCode]; 

LayoutErrorCode: type ■ {onTopOfAnotheritem, notEnuflabsOefined}; 



26.2.12 Multinational items 

Fiushness: type > simpieTextoispiay.Flushness; 

StreakSuccession: type » simpieTextOispiay.StreakSuccession; 

GetFtushness: procedure [ 
window: window.Handle, 
item: ItemKey] 
returns [old: Fiushness]; 

SetFlushness: procedure [ 
window: window.Handle, 
item: ItemKey, 
new:Flushness] 
RETURNS [old:Flushness]; 

GetStreakSuccession: procedure [ 
window: window.Handle, 
item: ItemKey] 

RETURNS [old: StreakSuccession]; 

SetStreakSuccession: procedure [ 
window: window.Handle, 
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item: Item Key, 
new:StreakSuccession] 
RETURNS [old : StreakSuccession] ; 

26.3 Usage/Examples 

26.3.1 Calling ChangeProcs 

The client has three ways to determine if an item has been changed. (I) The client may 
supply a GiobalChangeProc that governs the entire window, (2) it may supply a 
XXXChangeProc for certain items (such as choice and boolean), and (3) it may examine the 
"changed" boolean associated with each item. 

An item can change because the user changes the item, because a client calls 
SetXXXItem Value, or because a client calls Restore. 

The two kinds of change procs are called whenever the "changed" boolean goes from false 
to true (whether that is caused by user actions or client actions). The following describes 
the exact order of events for each source of change: 

• User action 

1. Change value of item and set "changed" boolean. 

2. Call local change proc, if any. 

3. Call global change proc, if any. 

• Client call to SetXXXItemValue 

1. Change value of item and set "changed" boolean. 

2. Call local change proc, if any. 

3. Call global change proc, if any. 

• Client call to Restore 

1. Change value of item and set "changed" boolean. 

2. Call global change proc, if any, with nuilltemKey. 

Note: If a change proc does a SetXXXItemValue, the client should take extreme care to 
prevent infinite recursion. 

26.3.2 Creating a Simple FormWindow 

Myltems: type ■ {boolean, choice, text}; 



shell: StarWindowShell.Handle <- StarWindowSheii.Create [...]; 
formWindow: window. Handle starWindowSheii.CreateBody [sheil]; 
FormWindow.Create [window: formWindow, makeitems: Makeltems, 
layoutProc: DoLayoutj; 
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Makeitems: Formwindow.MakettemsProc ■ { 

<< [window: Window.Handle, clientData: LONG POINTER] >> 
tag: xstring.ReaderBody; 

— Make a boolean item 

BEGIN 

booleanLabei: Formwindow.BooleanltemLabei <- [string( 

xstring.FromSTRING ["This is a boolean item'*Ll]l; 
tag 4-xstring.FromSTRING ["Tag"Ll; 
Formwindow.MakeBooleanltem [ 

window: window, myKey: Myltems.booiean.ORO, 

tag: @tag, label: booleanLabei, 

initSoolean: false]; 
end; 

— IVIake a choice item 

BEGIN 

choicel: xstring.ReaderBody «-xstring.FromSTRIN<a["Choice One'^L]; 
choiceZ: xstring.ReaderBody <-xstring.FromSTRING{"Choice 2"L]; 
choices: array [0..2) of Formwindow.Choiceitem «- [ 

[ stringCO, choicel] ], 

[ string[1, choiceZ] } ]; 
tag 4- xstring.FromSTRING ["Choice item"L]; 
FormWindow.MakeChoiceltem [ 

window: window, myKey: Myltems.choice.ORO, 

tag: @tag, values: OESCRiPTOR[choices], 

initChoice: 0]; 
end; 

-- Make a text item 

tag 4- xstring.FromSTRING ["Text item"L]; 

ForcnWindow.MakeTextltem[ 

window: window, myKey: Myitems.text.ORO, 

tag : @tag, width : 30] ; 

}; 

DoLayout: Formwindow.LayoutProc ■ { 

<< [window: window.Handle. clientData: LONG POINTER] > > 

Form Window. SetTabStops [window: window, tabStops: [ fixed [100] ] ]; 

line: Formwindow.Line 4~FormWindow.AppendLine [window]; 

— Put boolean and choice item on line 1 

FormWindow.Appendltem[window, Myitems.boolean.ORD, line]; 
Formwindow.Appendltem[window, Myltems.choice.ORO, line]; 

— Put text item on line 2 
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line <- Form Window. Append Line [window]; 
Formwindow.Appendltem{window, Myitems.text.ORD, tine]; 

}; 

26.3.3 Specifying Bitmaps in Choice Items 

This example creates a choice item with three possible values. Two of them are bitmaps; 
one is a string. The initial value to be highlighted is #2, the string. 

"The bits. (These are in a global frame or a file. They MUST be around for the duration of 
the FormWindow since the bits are NOT copied.) 

bml :FormWindow.Bitmap 4-[height:48, width:64, bitsPerLine:64, bits:{@bitmap1[0],0, 0]]; 

bm2:FormWindow.Bitmap «-{height:48, width:64, bitsPerLine:64, bits:t@bitmap2[0],0, 0]]; 

bitmapl : array [0.,192) of word *~ (--some bits--]; 

bitmap2: array [0..192) of word <- [--some bits-]; 

choiceOther: xstring.ReaderBody «-xstring.FromSTRING["OTHER"]; 

choices: array [0..3) of FormWindow.Choiceitem 4- [ 

[bitmap(0, bml] ], 

[bitmap(1,bm2] ], 

[string[2, choiceOther] ] 

]; 

FormWindow. Ma IceChoi cel tem [ 
window: window, 
tag: ©tag, 

myKey: Myltems.choice.ORO, 
values: DESCRiPTOR[choices], 
changeProc: ChoiceChangeProc, 
initChoice: 2]; 

26.3.4 The N EXT Key and Text Items 

This example creates a text item that inserts a new item after itself every time the user 
presses the NEXT key. 

"Make the text item 

Makeitems: FormWindow.MakeltemsProc ■ 

BEGIN 



FormWindow.MakeTextitem[ 
window: window, 
myKey: Myltems.text.ORD, 
width: 50, 
tag: @tag, 

initString: @initStringLong, 
nextOutOfProc: TextNextOut]; 



end; 
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TextNextOut: Formwlndow.NextOutOfProc « 

BEGIN 

tag: xstring.ReaderBody «-xstring.FromSTRING["Inserted ltem:"L]; 

initString: xstrmg.ReaderBody <-xstring.FromSTRING{"i DARE you! Edit ME!"L]; 

'-Create a new line on which to display the new item 
nextLine: Formwindow.Line <~Forinwindow.LayoutinfoFromltem 

[wi ndow, Myltems.testChoice2.0R0] .1 ine ; 
line: Formwindow.Line <-FormWindow.lnsertLine[window, nextLine, 60]; 

"Create the new item. 
Form Window. MakeTextltem [ 

window: window, 

myKey: cntr, 

"Cntr is a counter to keep tracli of the next available 

— key number since all ItemKeys are unique 
width: 50, 
tag: ©tag, 

initString: @initString , 
nextOutOfProc: TextNextOut]; 

—Put the new item on the line 
FormWindow.Appenditem[ 

window: window, 

item: cntr, 

line: line]; 
cntr 4— cntr + 1 ; 

"Set the last item's NextOutOfProc to NIL 

[] «~ Form Window. SetNextOutOfProc[ window, item, NIL]; 

end; 

26.3.5 Window Items (Including Interaction with the NEXT Key) 

This example creates a window item that wishes to be given control when a user nexts 
into it. 

"Create the item 

Makeltems: FormWindow.MakeitemsProc « 

BEGIN 

dims: window. Dims <- [200,200]; 

myWindow FormWindow.MakeWindowltem[ 
window: window, 
myKey: Myitems.window.ORO, 
tag: @tag, 
size: dims, 
destroy Proc: nil, 
nextlntoProc: MyNextlnto]; 



-Set the display and notify procs 
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[] <-window.SetOispiayProc[myWindow, WindowltemOispiayProc]; 
[] «-TiP.SetTabieAndNotifyProc [window: myWindow, 
table: TiPStar.NormalTable{], notify: MyNotify]; 

end; 

"MyNextlnto is called when a user presses the NEXT key "into" the window item 
MyNextlnto: Formwindow.NextlntoProc ■ 

BEGIN 

—set the input focus so the window item gets all of the notifications 

TiP.SetlnputFocus [w: myWindow, talceslnput: true]; 

end; 

—FormWindow is notified when the window item no longer requires the next key so 
FormWindow can pass it along to the appropriate item 

MyNotify: tip. Notify Proc ■ 

BEGIN 

FOR Input: Tip.Results ^ results, Input.next until Input » nil oo 
WITH z: input select from 
atom ■ > select z.a from 
nextDown ■ > 

FormWindow.TakeNEXTKey 

[window: myWindow.GetParent, item: Myltems.window.ORO]; 

enocase; 
endcase; 

ENDLOOP; 

end; 

26.3.6 Hints 

This example creates a text item with an associated pop-up menu: 

Makeltems: FormWindow.MakeltemsProc ■ 
begin 

FormWindow. MakeTextltem[ 
window: window, 
myKey: Myitems.text.ORD, 
width: 50. 
tag: @tag, 

initString: @initString, 
hintsProc: TextHints]; 

end; 

—Every time TextHints is called, specify the strings to put into the pop- up menu. The 
hintAction specifies that when a string is selected from the hints menu, it should replace 
the string in the text item 
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TextHints: FormWindow.TextHintsProc ■ 

BEGIN 

hintsArray < — some computation—; 

RETURN [hints: DESCRiPTOR(hlntsArray],freeHints: FreeHints, hIntAction: replace]; 
end; 

FreeHints: Formwsndow.FreeTextHintsProc ■ 

BEGIN 

—Free the strings and whatever other storage here 
end; 

26.3.7 Saving and Restoring Items 

The following example saves the original values of the items in a form window and 
restores them when the user presses RESET. 

—When creating the FormWindow also call 
FormWindow.Save{windOw]; 

—User changes some values 

—User decides he wants the original values back; presses Reset 
FormWindow.Restore{window]; 
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26.4Index of Interface Items 



Item 




Item 




Appendltein; procedure 


22 


HasAnyBeenChanged: procedure 


20 


AppendLine: procedure 


22 


HasBeenChanged: procedure 


20 


Bitmap: type 


26 


Insertltem: procedure 


23 


BooleanChangeProc: type 


8 


InsertLine: procedure 


23 


BooieanltemLabel: type 


8 


Isit: procedure 


5 


BooleanltemLabeiType: type 


8 


item:ltemKey 


5 


ChangeReason: type 


26 


ItemKey: type 


7 


ChoiceChangeProc: type 


11 


ItemType : type 


7 


ChoiceHintsPrQC* type 


11 


LayoutError: signal 


30 


Choicelndex: type 


10 


LayoutErrorCode: type 


30 


Choiceitem: type 


10 


Layout! nfoFromltem: procedure 


24 


Choiceltems: type 


10 


LayoutProc: type 


6 


ChoiceltemType: type 


10 


Line: type 


22 


CoitimanditemLabeii type 


13 


Li neUpBoxes : procedure 


24 


CommandltemLabelType: type 


13 


LookAtTextltemVaiue: procedure 


18 


CommandProc: type 


13 


Losing FocusProc: type 


27 


Create* procedure 


A 
•t 


MakeBooleanltem: procedure 


g 


DefaultLavout* LavoutPror 




MakeChoiceitem ' procedure 


Q 


def aultTabStops : TabStops 


25 


MakeCommandltem: procedure 


12 


Destroy: procedure 


4 


MakeDecimailtem: procedure 


14 


Destroi/ltem* procedure 


17 

1 # 


Makeinteaeritem ' procedure 

■ vflu ■ ■ li^^j w 1 1 k w Ilia r ni^^b tiT w 


15 


D^^troultAm^* 1>RnrFniiRF 


17 


MakeitemsProc type 


6 


Don^Lnnki nn AtT^ittltAiTi\/alij^" pRf^rpniiRF 


19 


MakeMulliioleChoiceltem* procedure 


1 1 


Error* error 


29 

••7 


MakeTagOnlyltem: procedure 


13 


ErrorCode* type 


k7 


MakeTextltem: procedure 


13 


Flushness: type 


30 


MakeWindowltem: procedure 


16 


FreeChoiceHintsProc: type 


11 


MinOimsChangeProc:TYPE 


5 


FreeTextHintsProc" type 


15 


MultipieChoiceChangeProc: type 


12 


GetBooleanltemValue: procedure 


18 


NeededOims: procedure 


6 


GetChaiceitemX/alije' proc!eoijre 


18 


NextintoProc* type 


28 


GetClientData* PRorEOURE 


4 


NextOutOfProc: type 


29 


6etDeciniallteni\/aiLi^* PROrpniiRE 


1S 


nextTabStOD* cardinal 


25 


GetFtushness: procedure 


30 


NewMakeCommandltem: procedure 


12 




c 

3 


noTabStOD' CARDINAL 




G^'tln'tpnprl'tpmX/aliJo* SROrpni ibp 

VSw Lit 1 ^CU^I 1 LCI II VOIUCa l^i^w^C wUnC 


1S 


nulllt@mK&\/* ItpniK^u 

I I U 1 ■ 1 % W III iX GWa IVdII IX C Y 


7 


GetMultiDleChoiceitein\/alue' procedure 

^ V VI VIWI %1 WI V^l IWI Wd II VOIUV* rnwWC vwl^fc 


18 


NumberOf Items* procedure 


g 


Gfi'tMe v+ Ai#a i la IiIpKpu * onnctm ire 


1Q 


OutlineOrHiohliaht'TYPP 


10 


fiof Noyf Out OfPmr* ppnccniiBR 




Renaint* PROrPniiRF 


C 
D 


GetReadOnlv: procedure 


26 


RemoveltemFromLine * procedure 


23 


GetStreakSuccession: procedure 


30 


ResetAliChanged: procedure 


21 


GetTabStops: procedure 


25 


ResetChanged: procedure 


20 


GetTag: procedure 


26 


Restore: procedure 


25 


GetTextltemValue: procedure 


18 


* Save: procedure 


25 


GetVisibility: procedure 


21 


SetAllChanged: procedure 


21 


GetWindowltemValue: procedure 


18 


SetBooleanltemValue: procedure 


19 


GetZone: procedure 


5 


SetChanged: procedure 


21 


GiobalChangeProc: type 


4 


SetChoiceitemValue: procedure 


19 
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Item Page 

SetOecimalltemValue: procedure 19 

SetFlushness: procedure 30 

SetGiobaiChangeProcs:PROCEEURE 5 

SetlnputFocus: procedure 27 

SetlntegerltemValue: procedure 19 

SetltemBox: procedure 25 

SetltemFont: procedure 27 

SetltemWidth: procedure 27 

SetLosjngFocusProc:PROCEDUfs 27 

SetMinOimsChangeProc: procedure 5 
SetMuitipleChoiceitemValue. procedure 20 

SetNextOutOfProc: procedure 29 

SetReadOnly: procedure 27 

SetSelection: procedure 26 

SetStreakSuccession: procedlre 30 

SetTabStops: procedure 25 

SetTextltemVaiue: procedure 20 

SetTookFocusProc: procedure 28 

SetVisibiiity: procedure 21 

SetWindowitemSize: proceolse 16 
SetWindowltemSizeExtra: procedure 17 

StreakSuccession: type 30 

TabStops: type 24 

TabType: type 24 

TakeNEXTKey: procedure 29 

TextH i ntAction : type 1 5 

TextHintsProc: type 15 

TookFocusProc: type 28 

Visibility: type 21 
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27.1 Overview 



The FormWindowMessageParse interface provides procedures that parse strings to 
produce various FormWindow TYPES. These strings are usually acquired from a message 
file. Currently, only FormWindow.Choiceltems are supported. 

27.2 Interface Items 

ParseChoiceltemMessage: procedure [ 

choiceltemMessage: xstring.Header, 

zone: uncounted zone] 
RETURNS [choiceitems : FormWindow.Choiceltems] ; 

Parses a choiceltemMessage (presumably retrieved using XMessage Get) vith the 
following syntax: "choiceString:choiceNumber@choiceString:choiceNumber@i". where 
choiceStrIng is the string to be displayed for that choice, choiceNumber is the fixed 
number associated with that choice, @ is the separator between choices, and | indicates 
the point at which to wrap the choices. The choices are displayed in the order they appear 
in the message, choiceitems is a descriptor for an array that must be freed by using 
FreeChoiceitems. 

FreeChoiceltems: PROCEDURE [ 

choiceltems:FormWtndow.Choiceitems, 
zone: uncounted zone]; 

Frees the array and everything it points to (strings). 



27.3 Usage/Examples 

The following example is taken from the folder implementation. The message acquired by 
XMessage.Get looks like "Sorted :0@Unsorted: 1". 

choices: FormWindow.Choiceltems ^—FormwindowMessageParse.ParseChoiceltemMessage [ 
XMessage.Get[mh, FolderOps.kpsSorted], z]; 
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FormWindowMessageParse 



FormWindow.MakeChoiceitem [ 
window: window, 
myKey: MyitemType.sorted.ORO, 
values: choices, 
initChoice: sorted.ORO, 
changeProc: SortedChanged ]; 



FormWindowMessageParse.FreeChoiceitems[choices, z]; 
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27.4 Index of Interface Items 

Item Page 

FreeChoiceitems: procedure 1 

ParseChoiceltemMessage: procedure 1 



27 Form Window IVI essage Parse 
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IdleControl 



28.1 Overview 

The IdleControl interface provides access to Viewpoint's basic controlling module. 

Viewpoint's control loop is organized as a series of two out-calls to a greeter procedure and 
a desktop procedure. Each procedure is implemented as a procedure variable, initialized to 
an appropriate no-op. 

Interface procedures allow the client to plug in its own greeter and desktop procedures. A 
plugged- in procedure is then called the next time that the control routine goes around the 
loop. 

28.2 Interface Items 

IdleControl keeps track of one GreeterProc and a list of DesktopProcs. A client may plug 
in a number of DesktopProcs and specify the one to be called by the value of the Atom.ATOM 
returned by the GreeterProc. 

28.2.1 Desktop Plug-in 

DesktopProc: type ■ proceoure; 

SetDesktopProc: procedure [atom: Atom.ATOM, desktop: DesktopProc] returns [old: 
DesktopProc]; 

SetDesktopProc allows the client to specify the desktop procedure to be called in the 
control loop, desktop is the procedure to be called, atom is the Atom.ATOM associated with 
desktop, old is the previously plugged-in desktop procedure. 

GetDesktopProc: procedure [atom: Atom.ATOM] returns [DesktopProc]; 

28.2.2 Greeter Plug-in 

GreeterProc: type « procedure returns [Atom.ATOM]; 
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SetGreeterProc: procedure [new: .GreeterProc] returns [old: GreeterProc]; 

SetGreeterProc allows the client to specify the greeter procedure to be called in the control 
loop, new is the procedure to be called, old is the previously plugged-in greeter procedure. 

« GetGreeterProc: procedure returns [GreeterProc]; 

DoTheGreeterProc: GreeterProc; 

DoTheGreeterProc calls the currently plugged-in GreeterProc. 

28.2.3 Idle Loop 

The control loop is the logical equivalent of: 
00 

atom: Atom.ATOM *- piuggedlnGreeterProc []; 
piuggedlnOesktopProc GetDesktopProcWithAtom(atoml; 
pi uggedl nOesktopProc{] ; 
endloop; 

Idle: procedure 

idle is called or PORKed to enter the idle state. Only clients who start the world should call 
Idle. 

28.3 Usage/Examples 

In the following example, the GreeterProc (IdleProc) displays a bouncing square on the 
screen. The GreeterProc is set in the mainline code of the module. The DesktopProc and 
GreeterProc can be initialized in different modules as long as they agree on the Atom.ATOM 
(in this case StarOesktop). 

starOesktopAtom: Atom.ATOM *- Atom.MakeAtom["StarOesktop"L]; 

IdleProc: idieControi. GreeterProc ■ begin —Display a bouncing square until the user 
presses any key 

return [StarOesktopAtom]; 

end; 

StarOesktop: procedure « begin 
"Do Star logon 

"Initialize and display Star desktop 

-Walt until Logoff 

end; 

I nit: PROCEDURE ■ 

begin 

[] 4- idieControi.SetGreeterProc[ldleProc]; 

[] <-idleControi.SetOesktopProc [starOesktopAtom, StarOesktop]; 
end; "Oflnit 
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28.4 Index of Interface Items 

Item Page 

DesktopProc: type 1 

OoThe<3reeterProc:GreeterProc 2 

DoTheGreeterProc:PROCEDURE 2 

GetOesktopProc 1 

GetGreeterProc: PROCEDURE 2 

GreeterProc: type 1 

Idle: PROCEDURE 2 

SetOesktopProc: procedure 1 

SetGreeterProc:PROCEDURE 2 
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KeyboardKey 



29.1 Overview 

KeyboardKey is a keyboard registration facility. It provides clients with a means of 
registering "system-wide" keyboards (available all the time, like English, French, 
European), a special keyboard (like Equations), and/or client-specific keyboards (such as 
these available only when the client has the input focus). The labels from these registered 
keyboards are displayed in the soft keys when the user holds down the KEYBOARD key. 

The client adds system keyboards by calling AddToSystemKeyboards. The client registers 
a special keyboard by calling RegisterCiientKey boards with the SPEClALKey board 
parameter. The client registers client-specific keyboards by calling 
RegisterClientKeyboards with the keyboards parameter. 

29.2 Interface Items 

29.2.1 System Keyboards 

A system keyboard is a one that is available to all clients who wish to recognize some 
general set of keyboards. (The default case is for a client to recognize system keyboards.) 
Examples of system keyboards are the various language keyboards— English, French, 
European,and so forth, and the general-purpose keyboards—Math, Office, Logic, and 
Dvorak. 

AddToSystemKeyboards: procedure (keyboard: BiackKeys-Keyboard]; 

The AddToSystemKeyboards procedure registers a client's keyboard interpretation with 
the keyboard key manager. The client is expected to provide a pointer to a keyboard 
record. This keyboard is made available whenever system keyboards are available. 

May raise ErrortalreadylnSystemKeyboards]. 

RemoveFromSystemKey boards: procedure (keyboard: BlackKeys.Keyboard]; 
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Removes a Keyboard from the list of system keyboards. 
May raise Error(notlnSystemKeyboards]. 

29.2.2 Client Keyboards 

A client keyboard is one that is specific to the application and has no meaning in a 
different context. Examples are the special keyboards (such as equations and fields) and 
Spreadsheet and 3270 keyboards. 

A client registers its keyboards with the keyboard manager when it gets control (gets the 
input focus). RegisterClientKeyboards tells the keyboard manager what keyboards ::<hould 
be made available to the user when the KEYBOARD key is held down. When the client loses 
control (releases the input focus) it should call RemoveCiientKeyboards to release its 
keyboards. Only 0-1 set of client keyboards is registered at any given time. If no client is 
registered, then all system keyboards are available to the user. 

RegisterClientKeyboards: procedure [ 
wantSy stem Keyboards: boolean <-true, 
SPECIALKey board: BlackKeys.Keyboard «- nil. 

keyboards: long descriptor for array of BiackKeys-KeyboardObject <- nil]; 

RegisterClientKeyboards establishes a list of client keyboards with the keyboard 
manager. This should occur at the same time the client takes the input focus. 
wantSystemKeyboards specifies whether the client wishes to recognize system keyboards. 
SPECIALKeyboard denotes the keyboard to be invoked by pressing the key combination of 
KEYBOARD key and the soft key labeled "Special". The keyboards array contains any other 
client keyboards. A client typically provides only a Special keyboard and 
wantSystemKeyboards = true. If wantSystemKeyboards * false ,the client should set one 
of his keyboards using SetKeyboard (see section 29.2.3). 

RemoveCiientKeyboards: procedure ; 

RemoveCiientKeyboards removes the client's keyboards from the keyboard manager's 
list. This list of available keyboards reverts to system keyboards only. The "Set " keyboard 
is the last system keyboard that was set (either by the user or a call to SetKeyboard). It is 
the client's responsibility to make sure his keyboards are removed when relinquishing 
control. It is appropriate for this to be done as part of a TiP.LosingFocusProc. 

29.2.3 Setting and Enumerating Keyboards 

Note: Most clients will probably not need to use the information in this section. 
SetKeyboard: procedure [keyboard: BiackKeys-Keyboard]; 

SetKeyboard sets the current keyboard to keyboard. This keyboard remains the current 
keyboard until the user presses a KEYBOARD key/SoftKeyOption/Set combination, which 
chooses a new keyboard, or until another SetKeyboard command is encountered. 

SetKeyboard is provided for those clients who have reason to set a keyboard 
programmatically. The usual case is for the user to set a keyboard by pressing the key 
combination KEYBOARD key/SomeSoftKeyDesignatingAKeyboard. However, for a client 
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calling ReglsterCiientKeyboards with wantSystem Keyboards > false it is appropriate to 
call SetKeyboard[@oneOfClientKeyboards] . (Otherwise the user could not type until he 
made a keyboard choice through the KEYBOARD key/SoftKey routine.) The other primary 
reason for calling SetKeyboard is to set an initial keyboard at boot time. 

EnumerateKey boards: procedure {class: KeyboardClass, enumProc: EnumerateProc]; 

EnumerateProc: TYPE » PR0CE0URE(key board: BlackKeys.Keyboard. class: KeyboardCIass] 

RETURNS(StOp: BOOLEAN 4- FALSE |; 

EnumerateKeyboards calls the specified EnumerateProc until the Stop boolean becomes 
TRUE or until there are no more keyboards to enumerate. When calling 
EnumerateKeyboards, the client may specify which keyboards he wants enumerated: 
system, client, special, or all of the registered keyboards. When the keyboard manager 
calls the client's EnumerateProc, the keyboard returned is qualified by class: client, 
system, or the special keyboard.. 

KeyboardCIass: type » (system, client, special, all, none}; 

system « A system keyboard is one that is available to all clients who wish to recognize 
some general set of keyboards. Examples of system keyboards are the various 
language keyboards - English, French, European, etc., and the general- 
purpose keyboards— Math, Office, Logic, and Dvorak. 

client « A client keyboard is one that is specific to the application. These are the 
keyboards registered in the keyboards array by the client calling 
ReglsterCiientKeyboards. 

special ■ A client-specific keyboard is invoked by pressing the combination of 
KEYBOARD key and the soft key labeled "Special". Specifically, this is the 
keyboard registered by the client as SPECiALKeyboard when calling 
RegisterClientKey boards. 

all ■ All keyboards: system, client, and special. 



29.2.4 Keyboard Window Plug-in 

This section pertains only to those clients interested in implementing a keyboard window 
facility. 

ShowKeyboardProc: type « procedure; 
SetShowKeyboardProc: procedure [ShowKeyboardProc); 
GetShowKeyboardProc: procedure returns [ShowKeyboardProc]; 

SetShowKeyboardProc and GetShowKeyboardProc provide an interface between a 
keyboard window application and KeyboardKey's "Show" key. The clients 
ShowKeyboardProc is called whenever the user presses the key combination KEYBOARD 
key/Show. This gives the client the opportunity to display a keyboard window. 
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29.2.5 Errors 

Error: ERROR(code: ErrorCode]; 

ErrorCode: type » {alreadylnSystemKeyboards, notinSystemKeyboards, 
insufficientSpace}: 

29.3 Usage/Examples 

29.3.1 AddToSystemKey boards Example 

In this application, a keyboard that will be useful across all applications has been detlned. 
Registering it as a system keyboard will make it available globally. 

useful Keyboard: BiackKeys.KeyboardObject «- 
[charTranslator: [proc: MyCharTrans.data: nil], 
pictureProc; MapPicture, 

label ^-xstring.FromStringcC/sefu/ Keyboard "L]]; 
KeyboardKey.AddToSystemKeyboards(@myUsefulKeyboard]; 

The keyboard manager adds the keyboard usefulKeyboard to the list of registered system 
keyboards and a key labeled Useful Keyboard to its labels for the KeyboardKey soft keys. 
When the user pushes the soft key labeled Useful Keyboard, MyCharTrans will be .0111^ 
registered as the Tip.CharTranslator, and if the keyboard window is open, MapPicture is 
called so that the picture and geometry table can be mapped. 

29.3.2 Special Keyboard Example 

This example contains a keyboard that is specific to a particular application and is 
available to the user through the Special key. The user should also be able to use the 
system keyboards in this application. Notice that it is appropriate to default the label 
when specifying a Special keyboard, because this keyboard is presented to the user as the 
current Special keyboard and is labeled as such. 

AddMyCllentKeyboards: procedure » 

BEGIN 

specialKeyboard:BlackKeys.KeyboardObject; 
fileName: xstring.ReaderBody *- xstring.FromSTRING("JSpecial.TIP"L|; 
table: TiP.Table 4-TiP.CreateTable[@fileName]; 
n 4-TiP.SetNotifyProcForTable(table. NotifyProc],- 
specialKeyboard <- [table: table]; 
KeyboardKey.RegisterCllentKeyboards( 
wa ntSystem Key boards : tru e, 
SPECIALKey board: ©special Keyboard]; 
END; - AddMyCllentKeyboards 

LosingFocusProc: tip. Losing FocusProc = ^pil^ 
< <Cw: window.Handle, data: long pointer] > > 

BEGIN 

Key boardKey.Remo veCl 1 entKey boa rds[] : 
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—release any data structures I don't want to keep around 
END; — LosingFocusProc 

29.3.3 Registering Multiple Client Keyboards Example 

This example deals with a client who has a special keyboard and several client-specific 
keyboards and does not plan to allow the user to use any system keyboards while in this 
application. 

keyboardRecords: array [o..3) of BlackKeys.KeyboardObject: -- Records filled in 
speciaiKeyboard: BiackKeys.Keyboard; - elsewhere 

AddCiientKeyboards: procedure « 

BEGIN 

KeyboardKey.RegisterClientKeyboardsi 
wantSystemKeyboards: false, 
SPECIALKey board: speciaiKeyboard. 
keyboards: DESCRiPTOR(keyboardRecords]]; 
KeyboardKey.SetKeyboard[@keyboardRecords(0]] 
END; - AddCiientKeyboards 

LosingFocusProc: Tip.LosingFocusProc s 
< <(w: window.Handle. data: long pointer} > > 

BEGIN 

KeyboardKey.RemoveClientKeyboardsO: 

release any data structures I don't want to keep around 
END; - LosingFocusPro 
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29.4 Index of Interface Items 



Item 


Page 


AddToSystemKeyboards: procedure 


1 


EnumerateKey boards: procedure 


3 


EnumerateProc: type 


3 


Error: error 


4 


ErrorCode: type 


4 


GetShowKeyboardProc: procedure 


3 


KeyboardClass: type 


3 


RegisterClientKeyboards: PROCEDURE 


2 


RemoveCiientKeyboards: procedure 


2 


RemoveFromSystemKeyboards: procedure 


1 


SetKeyboard: procedure 


2 


SetShowKeyboardProc: procedure 


3 


ShowKeyboardProc: type 


3 



KeyboardWindow 



30.1 Overview 

The BlackKeys and KeyboardKey interfaces provide the framework for including a 
keyboard window in ViewPoint. The window implementation is a plug-in (see 
KeyboardKey.SetShowKeyboardProc). This KeyboardWindow interface and its 
implementation provide one such keyboard window. 

30.2 Interface Items 
30.2. 1 Default Values 

defauitPtcture:Bia€kKeys.Picture; 
defaultGeometry: BiackKeys-GeometryTable.- 

The default values provided by this keyboard window implementation correspond to the 
standard English keyboard. 

DefaultPictureProc: BiackKeys-PictureProc; 

DefaultPictureProc returns defaultPicture and defaultGeometry to the caller when 
actions acquire. Clients may specify pictureProc: KeyboardWindow.DefaultPictureProc in 
their Bla<kKeys.KeyboardObject if they wish to display the default picture in the keyboard 
window while their keyboard is in effect. 

picture * BlackK«ys.nullPicture or BlackKeys.PictureProc » nil will result in the keyboard 
window displaying only gray in the viewing region. 
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30.2.2 Geometry Table Structure 

Geometry TabieEntry. type » record( 
box: Box. key: Keystations, shift: ShiftState]; 

Box: TYPE a RECORO(place: Window.Piace, width: INTEGER, height: INTEGER]; 

Area within the bitmap that generates a particular keystroke when selected with the 
mouse. 

Keystations: type ■ machine dependent { 

k1, k2, k3, k4, kS, k6, k7, kS, k9, klO, k11, k12. k13, k14, k15, k16, k17, 
k18, k19, k20, k21, k22, k23, k24, k25, k26, k27, k28, k29, k30, k31, k32, 
k33, k34, k35, k36, k37, k38, k39, k40, k41, k42, k43, k44, k45, k46, k47, 
k48, a1, a2, a3, a4, aS, a6, a7, a8, a9, alO, all, a12, iast(96) }: 

The following is a translation to LeveiiVKeys.KeyName: 



kl : 


= > One; 


k2 : 


= >Q; 


kS = 


= > A; 


k4 = 


= > Two: 


k5 = 


= >Z; 


k6 = 


= > W; 


k7 = 


= >S; 


k8 = 


= > Three; 


k9 = 


= > X; 


klO 


= >E; 


kll 


= >D; 


kl2 


= > Four; 


kl3 


= >C; 


kl4 


= > R: 


kl5 


= > F; 


kl6 


= > Five; 


kl7 


= > V; 


klS 


= >T; 


kl9 


= > G; 


k20 


= > Six; 


k2l 


= > B; 


k22 


= > Y; 


k23 


= >H; 


k24 


= > Seven; 


k25 


= >N; 


k26 


= >U; 


k27 


= > J; 


k28 


= > Eight; 


k29 


= > M; 


kSO 


= > I; 


k31 


= > K; 


k32 


= > Nine; 


k33 


= > Comma; 


k34 


= >0; 


k35 


= > L; 
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k36 = > Zero; 

k37 = > Period; 

k38 = > P; 

k39 = > SemiColon; 

k40 = > Minus; 

k41 = > Slash; 

k42 = > LeftBracket; 

k43 = > CloseQuote; 

k44 = > Equal; 

k45 = > RightBracket; 

k46 = > OpenQuote; 

k47 = > Key47; 

k48 = > Tab; 

al = > ParaTab; 

a2 = > BS; 

a3 = > Lock; 

a4 = > NewPara; 

a6 = > LeftShift; 

a6 = > RightShift; 

a7 = > Space; 

a8 = > AS; 

a9 = > A9; 

alO = > AlO; 

all => All; 

al2 = >A12; 

ShiftState: type » {None, One, Two. Both}.- 

Simulates the position of the shift keys associated with the keystroke. 

30.2.3 Bitmap Structure 

BiackKeys.Picture.bitmap is a long pointer. It is further defined within this keyboard 
window implementation as follows: bitmap points to the bits of the keyboard bitmap 
where dims = [505, 145] and bitmapBitWidth = 32*16. 

30.2.4 Getting to the Keyboard Window Handle 

GetDispiayWindow: procedure returns [window.Handle]: 
Returns handle to the body window of the keyboard window. 

30.3 Usage/Examples 

30.3.1 Using DefauitPictureProc 

OefineKey board: procedure a 

BEGIN 

nameString: xstring.ReaderBody 4-xstring.FromSTRING[''Zuiu"L] 
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zuluKeyboardRecord: BiackKeys-KeyboardObject «-( 
table: NIL. 

charTransiator: (MakeChar, nil]. 

pictureProc: KeyboardWindow.OefaultPictureProc, 

label: xstring.CopyToNewReaderBody(@nameString, Heap-systemZone]]; 
•'Save the pointer to the record somewhere for future use — 
END; —OefineKey board « 



30.3.2 Using defaultGeometry 

DeflneKeyboard: procedure a 

BEGIN 

nameString: xstring.ReaderBody <- xstring.FromSTRIN<3C"Swahili''L] 



swahiliKeyboardRecord: Black Keys.Key boardObject <-[ 

table: NIL. 

charTransiator: (MakeChar. nil], 
pictureProc: MapBitmapFiie. 

label: xstnng.CopyToNewReaderBody{@nameString, Heap.systemZone|]: 
"Save the pointer to the record somewhere for future use ~ 
END: -OefineKeyboard - 

MapBitmapFiie: BiackKeys.PictureProc » 

BEGIN 

pixPtr: BiackKeys.Picture.bitmap «-BlackKeys.nullPicture: 
SELECT action from 
acquire 

i—Do the right thing to map the bitmap. Uses the default Geometry table --. 
RETURNfpixPtr. KeyboardWindow.defaultGeometry] }; 
release s > {— Oo the right thing to unmap the bitmap 
RETURN(Bla€kKeys.nullPicture. NIL) } 
END; MapBitmapFiie 



box: [place: [x: XXX. y: XXXJ, w idth: XXX, height: XXXI, key: XXX, shift: XXX 



30.3.3 Sample Geometry Table Entries 



[[19, 111, 27, 271, k48, None 
[[51, 111,27, 141, kl. One 
[[51,241,27, 141, kl. None 
[[83,111,27, 14], k4, One 
[[83, 24], 27, 14], k4, None 



— 'tab' l<ey, dims: whole Icey picture 

" shifted '1' key, dims: upper half key 

— '1' key, dims: lower half key 

" shifted '2' key, dims: upper half key 

— '2* key, dims: lower half key 
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Item Page 

bitmap structure 3 

Box: TYPE 2 

defauitGeometry: BiackKey$.Geometry Table 1 

defaultPicture: BiackKeys-Picture 1 

DefaultPictureProc: Bia<kKeys.PictureProc 1 

Geometry TableEntry: type 2 

GetOisplay Window: procedure 3 

Keystations: TYPE 2 

ShiftState: type 3 
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31.1 Overview 

LeveilVKeys is documented in the Pilot Programmer's Manual (610E00160); however, the 
names of several keys were changed for ViewPoint. The key names now more closely 
match the names on the physical keys. 

31.2 Interface Items 

OPEN ks: KeyboardWindovv.KeyStations; 
OownUp: TYPE a ks.OownUp; 
Bit: TYPE » ks.Bit: 

KeyBits: type » packed array KeyName of DownUp; 

KeyName: type = machine dependent ( 
notAKey(O), 

Keysetl(ks.KSI), Keyset2(ks.KS2), Keyset3(ks.KS3), Keyset4(ks.KS4K 
KeysetS(ks.KS5), 

MouseLeft(k$.M1). MouseRight(ks.M3K MouseMiddie(ks.M2K 
Five(ks.k16), Four(ks.k12), Six(ks.k20), E(ks.k10K Seven(ks.k24), 
0(ks.k11). U(ks.k26K V(ks.k17),Zero(ks.k36), K(ks.k31h Minus(ks.k40), 
P(ks.k38), Slash(ks.k41), Font(ks.R8), Same(ks.L8), BS(ks.A2). 
Three(ks.k8), Two(ks.l<4), W(ks.k6), Q(ks.k2). S(ks.k7), A(ks.k3), 
Nine(ks.k32), Kks.kSO), X(ks.k9), 0(ks.k34), L(ks.k35), Comma(ks.k33), 
CloseQuote(ks.k43), RightBracket(ks.k45), Open(ks.LII), Keyboard(ks.RII). 
One(ks.kl). Tab(ks.k48), ParaTab(ks.A1), F(ks.k15K Props(ks.L12K 
C(ks.k13). J(ks.k27), B(ks.k21), Z(ks.k5). LeftShift(ks.A5), 
Period(ks.k37), SemiColon(ks.k39), NewPara(ks.A4), 
OpenQuote(ks.k46), Delete(ks.L3), Next(ks.RI), R(ks.k14), T(ks.k18), 
G(ks.k19), Y(ks.k22), H(ks.k23). Eight(ks.k28), N(ks.k25), M(ks.k29). 
Lock(ks.A3), Space(ks.A7), LeftBracket(ks.k42), Equal(ks.k44), 
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RightShift(ks.A6K Stop(ks.R12), Move(ks.L9), Undo(ks.R6), Margins(ks.R5K 
R9(ks.R9), LIO(ks.LlO). L7(ks.L7), L4(ks.L4), LI(ks.LI). A9(ks.A9), 
R10(ks.R10). A8(ks.A8), Copy(ks.L6), Find(ks.L5h Again(ks.L2), 
Help(ks.R2), Expancl(ks.R7), R4(ks.R4), 02(ks.02K DI(ks.DI), 
Center(ks.T2), TI(ks.TI). Bold(ks.T3), ltalics(ks.T4), Underline(ks.T5). 
Superscript(ks.T6), Subscript(ks.T7), Smaller(ks.T8K TIO(ks.TIO), 
R3(ks.R3), Key47(ks.k47), AIO(ks.AIO), Defauits(ks.T9). A1 1(ks.A1 1). 
A12<ks.A12)}: 
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31.3 Index of Interface Items 
Item 



Page 



OownUp: Type 
Bit: Type 
Key Bits: Type: 
Key Name: Type 

OPEN l(s:KeyboardWindow.KeyStations 
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MenuData 



32.1 Overview 

The MenuOata interface defines the data abstraction that is a titled list of named 
commands. It defines the object formats for a menu item and a menu as well as how to 
create and manipulate these objects. It is not concerned with how a menu might be 
displayed to a user. 

32.2 Interface Items 

32.2.1 Menu and Item Creation 

Items and menus are the two primary data objects in the MenuOata interface. Items are a 
name-procedure pair that constitute a command. Menus are an abstraction representing a 
collection of items to be presented to the user. These objects can be built and deallocated 
through this interface. 

Createitem: PROCEDURE [ 
zone: uncounted zone, 
nanie:xstrmg.Reader, 
proc: MenuProc, 
itemOata: long unspecified 0] 
RETURNS [ItemHandie]; 

ItemHandie: type a long pointer to Item; 

Item: type ■ Privateltem; 

MenuProc: type ■ procedure [ 

window: window.Handle, menu: MenuHandle, itemOata: long unspecified]; 

Createitem builds an item record in the indicated zone to be added to a menu. The name 
parameter is copied so it can be in the client's local frame. The proc parameter is the 
command procedure that is associated with a command name in an item. Client data that 
must be available when the MenuProc is called can be passed via the itemOata 
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parameter, zone can be nil, in which case MenuOata supplies its own zone (see PublicZone 
below). 

An Item is the representation for a {command-aame, command-procedure} pair. The 
"name Width" field, if non-zero, is the display width of the name. It may be set by a module 
that computes the width using SetltemNameWidth (see §32.2.3). Except for that, an item 
is read-only. 

Destroyltem: procedure [zone: uncounted zone, item: ItemHandle]; 

This procedure destroys the item, recovering the space, zone must be the zone in which the 
item was created, and item is the ItemHandle returned by Createltem. The item should 
not be in use when this procedure is called. 

CreateMenu: procedure! 
zone: uncounted zone, 
title: ItemHandle, 
array: ArrayHandle, 

copyltemslntoMenusZone: boolean «~ false] 
RETURNS [MenuHandle]; 

ArrayHandle: type « long descriptor for array of hsmHandle; 

MenuHandle: type ■ long pointer to MenuObject; 

MenuObject: type ■ PrivateMenu; 

CreateMenu builds a menu record in zone, title is an item containing the menu's title, 
array contains the collection of items that make up the menu. The items pointed to by the 
array and the title parameters are copied only if copyltemslntoMenusZone is true. 
Because item records are read-only, an item can be in several menus without copying. The 
procedure associated with the title item is currently unused and should be nil for future 
compatibility, zone can be nil, in which case MenuOata supplies its own zone (see 
PublicZone below). 

DestroyMenu: procedure [zone: uncounted zone, menu: MenuHandle] 

OestroyMenu destroys the menu, recovering the space, zone must be the zone in which 
the menu was created; menu is the MenuHandle returned by CreateMenu. It should only 
be called when the menu is not in use. There is no explicit way to test if a menu is in use. 

PublicZone: procedure returns [uncounted zone].- 

PublicZone returns the zone used by MenuOata when Createltem or CreateMenu is called 
with zone ■ nil. 

32.2.2 Menu Manipulation 

Addltem: procedure [menu: MenuHandle, new: ItemHandle] » 
inline {menu.swapltemProc [menu: menu, old: nil, new: new]}; 
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Subtractltem: procedure [menu: MenuHandle, old: ItemHandie] » 
INLINE {menu.swapltemProc [menu: menu, old: old, new: nil]}; 

Swapitem: procedure [ menu: MenuHandle, old, new: ItemHandie] ■ 
inline {menu.swapltemProc [menu: menu, old: old, new: new]}; 

These procedures alter a menu in the obvious ways. They call through the swapltemProc 
field in the menu object. This allows a module that posts a menu to "plant" a procedure in 
the swapltemProc field and thus get control on add/subtract/swap requests. With control, 
data can be monitored appropriately. 

SetSwapltemProc: procedure [menu: MenuHandle, new: SwapltemProc] 
RETURNS [old: SwapltemProc]; 

SwapltemProc: type « procedure [menu: MenuHandle, old, new: ItemHandie]; 

The SwapltemProc is the work horse for manipulating menus, as evidenced by the inline 
calls above. It can be changed by calling SetSwapltemProc. 

UnpostedSwapltemProc: SwapltemProc; 

This procedure is the standard one that is placed in a menu's swapltemProc when the 
menu is created. It is in the MenuOata implementation, and it can handle altering a menu 
when it is not posted. As discussed above, if a routine that posts a menu wants to get 
control of attempted menu alterations, it should alter the swapltemProc in the menu. 
When it has finished posting the menu, it should store MenuOata.UnpostedSwapitemProc 
as the swapltemProc. Alternatively, it can call wienuData.UnpostedSwapltemProc from 
within its own swapltemProc to perform the actual alteration of the menu object. 



32.2.3 Accessing Data 

The following provide procedural access to the internal data structures for an item or 
menu. 

ItemData: procedure [item: ItemHandie] returns [long unspecified]; 

ItemName: procedure [Item: ItemHandie] 
returns [name: xstring.ReaderBody]; 

SetltemNameWldth: procedure [item: ItemHandie, width: cardinal] ■ 
inline (item.nameWidth «- width); 

ItemNameWidth: procedure [item: ItemHandie] returns [cardinal] « 
INLINE (RETURN [Item.nameWidth]}; 

ItemProc: procedure [item: ItemHandie] returns [proc: MenuProc] « 
INLINE {return [item.proc]}; 

MenuArray: procedure [menu: MenuHandle] returns [array: ArrayHandle] a 
INLINE (RETURN [menu.array]}; 
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MenuTitte: procedure [menu: MenuHandle] returns [title: ItemHandle] » 
INLINE {RETURN [menu.title]}; 

Note: MenuObjects and Items are private records that are of use to menu posters but not 
of interest to general clients. The private records shown below are purely informative. 

Privateltem: TYPE > private record [ 
proc: MenuProc, 
nameWidth: natural, 
nameBytes: natural, 
body: select hasltemOata: boolean from 
false a > [nam« xstring.ByteSequence], 

true ■ > [itemOata: long unspegfieo, name: xstring.ByteSequence] 
endcase]; 



PrivateMenu: TYPE ■ private record [ 
zone: uncounted zone, 
swapltemProc: SwapltemProc, 
title: ItemHandle «~nil, 
array: ArrayHandle 4--NIL, 
arrayAllocatedltemHandles: natural <-0, 
itemslnMenusZone: boolean <- false] ; 



32.3 Usage/Examples 

A mechanism outside the scope of this interface displays a menu to the user. A given 
menu instance cannot ordinarily be displayed more than once at the same time. 

When the user asks that a command be executed, the command item's procedure is called. 
The window argument is a pointer that is dependent on the display mechanism; it might 
be the starWindowSheiLHandle that the menu is posted in. 



32.3.1 Example 1 

sysZ: UNCOUNTED ZONE ■ Heap.systemZone; 
I nit: PROC ■ { 

sampleTool: xstring.ReaderBody <-xstring.FromSTRING["Sample Tool"L]; 
Attention.AddMenuitem [ 
MenuData.Createltem [ 

zone: sysZ, 

name: @sampleTool, 

proc: MenuProcl ] }; 

MenuProc: MenuOata.MenuProc • { 

another: xstring.ReaderBody <-xstring.FromSTRING("Another"Ll; 
repaint: xstring.ReaderBody 4-xstring.FromSTRiNG["Repaint"L]; 
post: xstring.ReaderBody <-xstring.FromSTRING["Post A Message"L]; 
sampleTool: xstring.ReaderBody 4- xstring.FromSTRiNG["Sample Tool"L]; 
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— Create the StarWindowSheU. - 

shell: starWindowSheiLHandle « starWindowSheiLCreate [name: @sampleTool]; 



" Create some menu items. -- 

z: UNCOUNTED ZONE <-StarWindowSheil.GetZone [shell]; 

Items: array [0..3) OF MenuOata.ltemHandle [ 

MenuData.Createitem [zone: z, name: ©another, proc: MenuProc], 
MenuOata.Createitem [zone: z, name: ©repaint, proc: RepalntMenuProc], 
M«nuOata.Createltem [zone: z, name: @post, proc: Post] ]; 

myMenu: MenuData.MenuHandle ■ M«nuOata.CreateMenu [ 
zone: z, 
title: NiLt 

array: descriptor [items] ]; 
starWindowSheii.SetRegularCommands [sws: shell, commands: myMenu]; 



}; 



Post: MenuOata.MenuProc a { 

msg: xstring.ReaderBody <-xstring.FromSTRING ["This is a sample attention window 

message."Ll; 

Attention.Post [@msg] }; 

RepaintMenuProc: MenuOata.MenuProc =« { 

body: window.Handle ■ starWindowSheli-GetBody [[window]]; 
window.lnvalidateBox[body, [[0, 0], [30000, 30000] ]]; 
Window. Validate[body] }; 

" Mainline code ~ 

lnit(]; 



32.3.2 Example 2 

~ Declare and create an item title and command array to be placed in a menu - 
mouseMenuTltle: AAenuOata.itemHandle InitMouseMenuTitle []; 
mouseMenuCmnds: array [0..10) OFMenuOataJtemHandle; 

— Create the menu — 

mouseMenu: MenuData.MenuHandle ^MenuOata.CreateMenu [ 
zone: MenuOata.PublicZone [],— could be a client-supplied zone 
title: mouseMenuTitle, 

array: descriptor [@mouseMenuCmnds[0], 1] ]; 
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CommandProc: MenuOata.MenuProc « { 

"Does something reasonable for the corresponding item — }; 



InitMouseMenuTitle: PROCEDURE RETURNS [MenuOata.ltemHandie] « { 
zone: uncounted zone ^MenuOata.PublicZone []; 
mouseBitMap: array [0..1 5) of word [ - ... acta^ code - ]; 
mouseSymbolChar: xstrthg.Character <- 

simpieTextFont-AddClientDef inedCharacter [ — ... parameters — ]; 
mouseString: xstring.ReaderBody 4-xstring.FromChar [@mouseSymboiChar]; 
cmndTitle: xstring.ReaderBody ^xstring.FromSTRING ["Command"]; 
mouseMenuCmnds[0] <~MenuData.Createitem [zone, @cmndTitle, CommandProc]; 
return [MenuOata.Createitem [zone, @mouseString, NIL] ] }; 

The above example is just one technique for initializing a menu. The routine 
InitMouseMenuTitle places variables that don't need to be global in the local frame . Pay 
close attention to placement of variables to prevent dangling references. 
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32.4 Index of Interface Items 



Item 


Page 


Aaaiiem. procedure 


4, 


Arraynanaie. type 


i. 
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ItemProci procedure 
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PrivateMenu:TYPE 


4 


PubiicZone: procedure 


2 


SetltemNameWidth: procedure 


3 


SetSwapltemProc: procedure 


3 


Subtractltem: procedure 


3 


Swapltem: procedure 


3 


SwapltemProc: type 


3 


UnpostedSwapltemProc: SwapitemProc 


3 
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33.1 Overview 

MessageWindow provides a facility for posting messages in a window to the user. This is 
similar to posting messages using the Attention interface, but many message windows 
can be on the screen at once, while there is only one attention window. A message window 
is usually a short window with less than 10 lines of text in it. As more messages are 
posted, previous messages scroll off. 

MessageWindow. Create takes a "plain" window, typically obtained by calling 
starWindowSheiiXreateBody or FormWindow.MakfaWindowltenri, and turns it into a message 
window. Messages may then be posted by calling Post. To clear the window, call Clear. 
Various types may be formatted into messages to be posted in the window by using the 
XFormat-Object returned by XFormatObject. 

33.2 Interface Items 

33.2.1 Create, Destroy, etc. 

Create: procedure [window: window.Handle, 

zone: uncounted zone <- nil. lines: cardinal 4-10]; 

Create turns window into a message window, zone will be used for storage of any strings 
posted. If zone is nil, a private zone is used, lines is the number of lines of text to display. 
After more than lines of text are posted, the oldest lines are scrolled out of the window. Fine 
point: The current ViewPoint implementation does not support user scrolling. 

Destroy: procedure [window.Handle]; 

Destroy turns the window back into an ordinary window, destroying any 
MessageWindow specific context associated with the window. It does not destroy the 
window. 

Isit: procedure [window.Handle] returns [yes: boolean]; 

isit returns true if the window was made into a message window by a call to Create. 
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33.2.2 Posting messages 

Post: PROCEDURE [window: window.Handle, 
r: xstring.Reader, clear: boolean 4-true]; 

Post displays r in window. If dear is true, r starts on a new line. If clear is false, r is 
appended to the last line posted. 

PostSTRING: procedure [window: window.Handle, 
s: LONG STRING, clear: BOOLEAN 4- true] ■ inline 

BEGIN 

r: xstring. Reader Body ^xstring.FromSTRlNG [s]; 
MessageWindow.Post [window, @r, clear]; 
end; 

PostSTRING posts s in window. If clear is true, r starts on a new line. If clear is false, r is 
appended to the last line posted. 

Clear: procedure [window: window. Handle]; 

Clear clears the entire window. 

XFormatObject: procedure [window: window.Handle] returns [o: xFormat.Object]; 

XFormatObject returns an XFormat.Object that can be used to post messages in window. 
The format procedure logically calls Post with clear « FALSE. (See examples.) 

33.3 Usage/Examples 

In the following example, a client displays the name and size of a file. It uses the NSFile 
interface to access the file and get the name and size attributes. See the Services 
Programmer's Guide (610E00180)--Fi/mg Programmer's Manual for documentation on 
the NSFile interface. The example intermixes use of the format handle and use of the Post 
procedure. 

msgW: window.Handle ^Formwindow.MakeWindowltem [. . .]; 
Message Window.Create [window: msgW, tines: 5]; 

PostNameAndSize [file, msgW]; 

PostNameAndSize: procedure [file: NSFiie.Handle, msgW: window.Handle ] ■ { 
nameSelections: NSFiie.Selections ■ [interpreted: [name: true]]; 
attri butes : NSFiie.Attri butesRecord; 

msgWFormat: XFormat.Object 4-~Messagewindow.XFormatObject[msgW]; 
rb: xstring.ReaderBody <- Message[theFile]; 

Messagewindow.Post[window: msgW, s: @rb, clear: true]; -> start a new message 
XFormat.NSString[@msgWFormat, attri butes. name]; 
xFormat.ReaderBody[h: @msgWFormat, rb: Message(contains]]; 
XFormat.Oecimal[h: @msgWFormat, n: NSFiie.GetSizelnBytes[file]]; 
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rb 4- Message[bytes]; 

Messagewindow.Post[window: msgW, s: @rb]}; - dear defaults to true 

Message: procedure [key: {theFiie, contains, bytes}] returns [xstring.ReaderBody] > { 
...}; 

An example of the resulting message displayed in the message window is 
The file Foe contains 53324 bytes 
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33.4 Index of Interface Items 



Item 


Page 


Clear: procedure 


2 


Create: procedure 


1 


Destroy: procedure 


1 


Islt: procedure 


1 


Post: procedure 


2 


PostSTRING: procedure 


2 


XFormatObject: procedure 


2 
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34.1 Overview 

OptionFile reads values from profile files (text files). with the following format: 
[Section] 

Entry 1: TRUE — a boolean entry 
Entry2: A string value 
EntryS: 123 — an integer entry 

These files are primarily used for keeping user options across logon and boot sessions ( thus 
the name profile file). Applications typically read various options out of the current user 
profile file at logon. These options often specify default values for properties, the behavior 
of the application, or both. 

34.2 Interface Items 

34.2.1 Getting Values from a File 

Each GetXXXValue procedure takes a section name and an entry name that identifies the 
entry. It is expected that the section and entry strings are obtained from XMessage. Each 
also takes a file. If file is defaulted, the current user profile is used (see the Current 
Profiles section below). All these procedures may raise Error [invalidParameters, 
inconsistentValue, notFound, syntaxError]. 

GetBooleanVaiue: procedure [section, entry: xstring. Reader, 
file: NSFiie.Reference 4-NSFiie.nullReference] 
RETURNS [value: boolean]; 

GetBooleanVaiue returns the value of a boolean entry. The entry must contain either 
"TRUE" or "FALSE" or the translated string for true or false as defined in the message 
files. 

Getlnteger Value: procedure [section, entry: xstring.Reader, 

index: cardinal <-0, file: NSFUe.Reference 4~NSFne.nullReference] 
returns [value: long integer]; 



34-1 



34 



OptionFUe 



GetlntegerVaiue returns the value of an integer entry. The entry must contain a number 
that can be parsed by xstring.ReaderToNumber. index causes the indexth entry to be read, 
for repeating entries. 

GetStringValue: procedure [section, entry: xstring.Reader, 

cailBack: procedure [value: xstrmg.Reader], index: cardinal 0, 
file: NSFiie.Reference «~NSFiie.nullReference]; 

GetStringValue calls callBack with the value of a string entry, index causes the indexth 
entry to be read, for repeating entries. 

34.2.2 Current Profiles 

ViewPoint supports a current user profile file and a workstation profile file. The current 
user profile is automatically changed whenever a user logs on or off. The workstation 
profile contains entries specific to the workstation rather than specific to each user. There 
is one workstation profile on each workstation. 

GetUserProfiie: procedure returns [file: NSFiie.Reference]; 

GetUserProfiie returns the current User profile file. Note: Each of the Get and Enumerate 
procedures uses this file as the file parameter is defaulted. 

GetWorkstationProfile: procedure returns [file: NSFiie. Reference] ; 

GetWorkStationProfile returns the current workstation profile file. 

34.2.3 Enumerating a File 

EnumerateXXX are useful for applications that look for the same entry in all sections. 

EnumerateSections: procedure [callBack: SectionEnumProc, 
file: NSFiie.Reference <e-NSFiie.nultReference]; 

SectionEnumProc: TYPE » procedure [section: xstring.Reader] 

RETURNS [stop: BOOLEAN ^ FALSE],' 

EnumerateSections calls callBack for each section in file, until stop » true. If file is 
defaulted, the current user profile is used. 

EnumerateEntries: procedure [section: xstring.Reader, callBack: EntryEnumProc, 
file: NSFiie.Reference «-NSFiie.nullReference]; 

EntryEnumProc: type « procedure [entry: xstring.Reader] 

RETURNS [stop: BOOLEAN 4- FALSE],' 

EnumerateEntries calls callBack for each entry in section in file, until stop « true. If file is 
defaulted, the current user profile is used. 
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34.2.4 Errors 



Error: error [code: ErrorCode]; 

ErrorCode: type ■ {invaiidParameters, inconsistentVaiue. notFound, syntaxError}; 
invaiidParameters such as passing in a nil string. 



inconsistentVaiue 

notFound 

invalldFiie 

syntaxError 

NotAProfiieFile: signal; 



calling GetBoolean Value for an entry that does not have true 
or FALSE as its value, or calling GetlntegerValue for an entry 
that will not parse as number. 

asking for an entry that is not in the file. 

reading from a file that is not a profile file. 

garbage in the file. 



The passed file is not a profile file; it has the wrong file type. RESUMEing will read the file 
anyway. 



34.3 Usage/Examples 

— In global frame 
displayMessage: BOOLEAN 4- true; 

whereToOispiay: SampleBWSApplicationops.WhereToOisplay *- window; 
messageToOisplay: xstrmg. Reader <~ nil; 



- Called from initialization code 
GetOptionsAtLogon: procedure ■ { 

logon: Atom.ATOM Atom.MakeAtom["Logon"L]; 

desktopRef : NSFiie.Reference; 

[] <(- Event.AddOependency (agent: LogonEvent, my Data: nil. event: logon]; 

IF (desktopRef 4- starDesktop.GetCurrentOesktopFiie []) # NSFiie.nuilReference then { 

— If the desktop is NOT null, then a user's already logged on, 

"i.e., we got loaded after logon. 
So we go read the options immediately by calling our 

— Event.AgentProcedure directly. — 

desktop: NSFUe.Handle NSFiie.OpenByRef erence [desktopRef]; 

[] <-LogonEvent [event: logon, eventData: loophole [desktop], myData: NIL]; 

NSFiift.Close [desktop]; 

}; 

}; 

LogonEvent: Event.AgentProcedure ■ { 

< < [event: Event.EventType, eventData: long pointer. 
myData: LONG pointer] 

RETURNS [remove: boolean <- false, veto: boolean <- false] > > 

open Ops: SampleBWSApplicationOps; 

mh: XMessage.Handle « ops.GetMessageHandle[]; 
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CopyMessageToOispiay: procedure [value: xstring.Reader] ■ { 
messageToOisplay <~ xstring.CopyReader [value, sysZ]}; 

GetWhereToOisplay: procedure [value: xstring.Reader] ■ { 

window: xstring.Reader Body <- XMessage.Get [mh, ops.kwindow]; 
attention: xstring.ReaderBody <- XMessage.Get [mh, Ops.kattention]; 
both: xstring.ReaderBody <- XMessage.Get [mh, Ops.lcboth]; 
whereToOisplay select true from 

xstring.Equivalent [value, ©window] « > window, 

xstring.Equivalent [value, ©attention] a > attention, 

xstring.Equivalent [value, @both] ■ > both, 

ENOCASE ■ > window; 

}; 

section: xstring.ReaderBody XMessage.Get [mh, Ops.kApplicationName]; 

entry: xstring.ReaderBody *- XMessage.Get [mh, Ops.kOispiayMessage]; 
displayMessage ^-OptionFiie.GetBooleanValue [©section, ©entry ! 
OptionFiie. Error ■ > continue]; 

entry XMessage.Get [mh, Ops.kMessageToOisplay]; 
OptionFiie.GetStringValue [©section, ©entry, CopyMessageToOispiay ! 
OptionFiie. Error > > continue]; 

entry <- XMessage.Get [mh, Ops.kWhereToDisplay]; 
OptionFiie.GetStringValue [©section, ©entry, GetWhereToOisplay ! 
OptionFiie. Error « > continue]; 

}; 
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34.4 Index of Interface Items 



Item Page 

EntryEnumProc: type 2 

EnumerateEntries: procedure 2 

EnumerateSections: procedure 2 

Error: error 3 

ErrorCode: type 3 

GetBooieanValue: procedure 1 

GetlntegerVaiue: procedure 1 

GetString Value: procedure 2 

GetUserProfile: procedure 2 

GetWorkstationProfile: procedure 2 

NotAProfiieFile: signal 3 

SectionEnumProc: type 2 
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35.1 Overview 

The PopupMenu interface provides a single procedure that posts a pop-up menu. 

35.2 Interface Items 

Popup: PROCEDURE ( 

menu: MenuOata.MenuHandle, 
ciients:window.Handle, 
showTitie: boolean *- true, 
place: window.Place (-1,-11 ]; 

This procedure causes the display of the client's menu at or near the indicated place in the 
rootWindow: if the place [-1,-11 is given, the current cursor position is used. If the point 
button goes up while the cursor is over one of the menu items, then that item's 
MenuData.MenuProc is called, clients is passed to the MenuOata.MenuProc as the window 
parameter. The showTitie field indicates whether the menu's title should be displayed 
above its command strings. 

The implementation assumes that the point button is down; consequently, the menu is 
displayed until the point button goes up. Popup does not return until the menu is taken 
down, regardless of whether a menu item is selected. 

35.3 Usage/Examples 

Much of the complication in using the PopupMenu interface stems from its reliance on 
MenuData. A thorough understanding of how to create a menu is needed before using this 
interface (see the MenuOata chapter for details). 

35.3.1 Example 

— Create the menu: 

myMenu: MenuOata.MenuHandle MenuOata.CreateMenu [ 
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Pass in miscellaneous parameters; see the MenuOata interface for details - ]; 

PopupMenu.Popup[ 
menu: myMenur 
clients: currentWindow]; 
- showTitle and place are defaulted in this call. 
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Item Page 

Popup: PROCEDURE 1 
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36.1 Overview 

ProductFactoring allows an application to determine whether the customer has purchased 
a particular application. ProductFactoring maintains a record of the applications that 
have been purchased (enabled) on the workstation's disk. Tools are provided to customers 
for enabling various applications (options). The enabling of an application is outside the 
scope of this interface. 

ProductFactoring also allows an application to register a name for its product option, thus 
allowing the product factoring tools to display meaningful names to their users. 

36.2 Interface Items 

36.2.1 Products and ProductOptions 

Product: TYPE » cardinal [0..1 6); 

A Product refers to a large set of software. (Also see the ProductFactoringProducts 
interface.) 

ProductOptlon: type ■ cardinal [0..28); 

A ProductOption refers to a particular piece of software that a customer can buy within a 
Product, such as Spreadsheets, Advanced Star Graphics, or Print Service. To obtain a 
ProductOption for a particular application, see your Xerox Sales Represenative. 

Option: TYPE ■ RECORD [product: Product, productOption: ProductOption]; 

nuilOption: Option « . . . ; 

An Option uniquely identifies a ProductOption within a Product. 

36.2.2 Checking for an Enable Option 

Enabled: procedure [option: Option] returns [enabled: boolean]; 
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Enabled returns true if option is enabled on this workstation, otherwise false. Typically, 
an application calls Enabled every time it is called to perform some user operation such as 
opening an icon. Enabled is fast; it does not read the file every time it is called. It may 
raise Error[notStarted1 if there is no product factoring file on the workstation. 



36.2.3 Describing a Product and an Option 

DescribeProduct: procedure [product: Product, desc: xstring. Reader]; 

Provides a name for product, desc is copied to an internal zone. May raise 
Error[illegaiProduct] if the value of product is out of range. 

OescribeOption: procedure [option: Option, desc: xstring.Reader, 
prerequisite: Prerequisite <- nullPrerequisite]; 

Prerequisite: type ■ record ( 

prerequisiteSpec: boolean ^ false, 
option: Option]; 

nullPrerequisite: Prerequisite » [false, nuilOption]; 

Describes option, desc is a name for the option, prerequisite specifies any other options 
that this option depends on. All data is copied to an internal zone. Use of this procedure 
overrides any earlier definition with the same option value. May raise 
Error[illegalProduct] if the value of option. product is out of range. May raise 
Error[illegaiOption] if the value of option. productOption is out of range. May raise 
Error[missingProduct] if option.product has not yet been defined. 

36.2.4 Errors 

Error: error [type: ErrorType]; 

ErrorType: type » { 

dataNotFound, notStarted, iilegalProduct, iliegaiOption, 
missingProduct, missingOption}; 

dataNotFound 

notStarted 

iilegalProduct 

iilegalOption 

missingProduct 

missingOption 

36.3 Usage/Examples 

— In global frame — 

sampleApplicationPFOption: ProductFactoring.ProductOption » 27; 



The product data file is missing. 

Start proc has not been called yet. 

Not a legal Product value. 

Not a legal ProductOption value. 

The Product specified has not yet been defined. 

The ProductOption specified has not yet been defined. 
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" 27 was chosen arbitrarily for this sample. -- 

— A real application should obtain a real ProductOption/ » 

— Called during initialization — 
InitProductFactoring: procedure ■ { 

mh: XMessage.Handle » SampfeBWSApplicationops.GetMessageHandle[]; 

rb: xstrmg.ReaderBody xM«ssage.Get [mh, 

SampleBWSAppiicationops.kAppiicationName]; 

ProductFactoring.OescribeOption [ 

option: [ product: ProductFactoringProducts.Star, 

productOption: sampJeApplicationPFOption], 
desc: @rb]; 

}; 

" GenericProc •• 

GenericProc: Containee. GenericProc > { 
IF 'ProductFactoring.Enabied [option: [ 

product: ProductFactoringProducts.Star, 
productOption: sampleAppiicationPFOption]] then { 
mh: XMessage.Handle 4- SampieBWSAppiicationops.GetMessageHandie[]; 
rb: xstring.ReaderBody XMessage.Get [mh, SampleBWSApplicationops.kNotEnabled1; 
ERROR Containee.Error [@rb]; 

}; 

SELECT atom FROM 
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36.4 Index of Interface Items 



Item Page 

OescribeProduct: procedure 2 

OescribeOption:PROCEOURE 2 

Enabled: procedure 1 

Error: error 2 

ErrorType: type 2 

nuliOption: Option 1 

nuilPrerequisite: Prerequisite 2 

Option: type 1 

Prerequisite: type 2 

Product: type 1 

ProductOption: type 1 
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37.1 Overview 

ProductFactoringProducts defines the ProductFactoring.Products for various Xerox products. 
(See the ProductFactoring interface). 

37.2 Interface Items 

Product: type » ProductFactoring.ProduCt; 
star: Product « 0; 

Star defines the Xerox Star (alca ViewPoint) workstation product. 
Services: Product » 1; 

Services defines the Xerox network services product. 
DFonts: Product « 3; 

OFonts defines the product for Xerox display fonts. 
PFonts: Product ■ 4; 

PFonts defines the product for Xerox printer fonts. 
Viewpoint: Product ■ 5; 

Viewpoint defines a product for Xerox ViewPoint applications. 
ViewPointApps: Product ■ 6; 

ViewPointApps defines a product for Xerox ViewPoint applications. 
Converter: Product ■ 7; 

Converter defines the product for Xerox ViewPoint converter icon applications. 
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Services2: Product ■ 8; 

Services2 defines another Xerox network services product. It is defined in 
ProductFactoringProductsExtras.mesa. 

Languages: Product ■ 9; 

Languages defines the Xerox languages product. It is defined in 
ProductFactoringProductsGxtras2.mesa. 

FujiUnique: Product ■ 10; 

FujiZUnique: Product « 11; 

FujiUnique and Fuji2Unique define Fuji Xerox products. These are defined in 
ProductFactoringProductsExtrasS.mesa. 

OahuUnique: Product ■ 12; 

OahuUnique defines the Xerox Oahu product. It is defined in 
ProductFactoringProductsE xtras4. mesa. 

RankUnique: Product « 13; 

RankUnique defines the Rank Xerox product. It is defined in 
ProductFactoringProductsExtras4.mesa. 
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37.3 Index of Interface Items 



Item Page 

Converter: Product 1 

DFonts: Product 1 

FujiUnique: Product 2 

Fuji2Unique: Product 2 • 

Languages: Product 2 

OahuUnique: Product 2 

PFonts: Product 1 

Product: type 1 

RankUnique: Product 2 

Services: Product 1 

Services2: Product 2 

Star: Product 1 

Viewpoint: Product 1 

ViewPointApps: Product 1 
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38.1 Overview 



The PropertySheet interface allows clients to create property sheets. A property sheet 
shows the user the properties of an object and allows the user to change these properties. 
Several different types of properties are supported. The most common ones are boolean, 
choice (enumerated), and text (see Figure 38. 1 ). 



Form Window 



Title 



Done 



Cancel 



Apply 



Defaults 



Tag I BOOLEAN ] Suffix 

[choice 1 ||||iiiiil|CHOICE3 I 



Tag 



Text item 



i 



T 



Figure 38. 1 . A Property Sheet 

From a client's point of view, a property sheet is a Star window shell with a form window 
as a body window. (See the StarWindowShell and FormWindow interfaces.) The 
FormWindow interface especially must be understood in order to create a property sheet. 



A property sheet is created by calling PropertySheet.Create, providing a procedure that will 
make the form items in the form window (a FormWindow. MakeltemsProc), a list of 
commands to put in the header of the property sheet, such as Done, Cancel, and Apply 
(PropertySheet.Menultems), and a procedure to call when the user selects one of these 
commands (a PropertySheet. MenuitemProc). PropertySheet.Create returns the 
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StarWindowSheli.Handle for the property sheet. When the user selects one of the commands 
in the header of the property sheet, the client's PropertySheet. MenultemProc is called. If the 
user selects Done , for example, the client can then verify and apply any changes the user 
made to the object's properties. 

PropertySheet also provides the capability to create linked property sheets. Several 
property sheets may be logically linked together in the same property sheet shell. This is 
accomplished by changing form windows within a property sheet's Star window shell and 
by having an additional choice item that specifies which form window is currently 
displayed. Linked property sheets are further described in the section on linked property 
sheets below. 

38.2 Interface Items 

38.2.1 Create a PropertySheet (Not a Linked One) 

Create: procedure [ 

formWindowltems: FormWindow.MakeltemsProc, 
menultemProc: MenultemProc, 
size: window.Oims, 

menultems: Menuitems <- propertySheetOefaultMenu, 

title: xstring.Reader <- nil, 

placeToOispiay: window.Place *- nullPlace, 

formWlndowltemsLayout:FormWindow.LayoutProc <- nil, 

windowAttachedTo: StarWindowSheli.Handle «- [NIL], 

globalChangeProc: FormWindow.GlobaiChangeProc <- nil, 

display: boolean ^true. 

ciientOata: long pointer nil, 

afterTakenOown: MenultemProc nil, 

zone: uncounted zone *- nil] 

returns [shell: starWindowSheii.Handle]; 

Create creates a property sheet. 

formWindowltems is a client-supplied procedure that is passed a body window of the 
property sheet. It should fill the window with the form items that make up the main body 
of the property sheet. (See the FormWindow interface for a full description of how to create 
form items in a window.) 

menultemProc is a client-supplied procedure that is called whenever the user selects one 
of the menu items in the header of the property sheet window. (See §38.2.2 below.) 

size is the preferred size of the property sheet's Star window shell. 

menultems specifies the menu items that are displayed in the header of the property 
sheet. The default is ? (help). Done, and Cancel. 

title is the title to be displayed in the header of the property sheet. 

placeToOispiay is the preferred location on the screen of the property sheet. If the default 
is taken, Create calculates the place to display. 

formWindowltemsLayout specifies the desired position of the form items in the 
FormWindow. (See FormWind.ow.LayoutProc for a full description.) If 
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formWindowltemsLayout is nil, then FormWindow.OefaultLayout of one item per line Is 
used 

windowAttachedTo is the StarWindowShell that this property sheet is showing 
properties for. If windowAttachedTo is not nil, then the user will not be able to close 
windowAttachedTo until this property sheet is closed. (See also 
StarWindowSh«ii.Create.hoSt.) 

globalChangeProc is called if any item in the main form window is changed. (See 
FormWindow.GiobalChangeProc for a full description.) 

display indicates whether the property sheet should actually be displayed on the screen 
(inserted into the visible window tree) or just created but not actually painted on the 
screen (not inserted into the visible window tree). If this is a property sheet for a file (if it is 
being created as the result of a call to a Containee.GenericProc [atom: Props]), then display 
should be FALSE and the StarWindowShell. Handle should be returned from the GenericProc so 
that, for example, the desktop implementation can put the property sheet on the display 
by calling StarWindowSheii.Push. 

cilentData is passed to formWindowltems, formWindowltemsLayout, and 

menultemPrOC. Fine point: formWindowltems will not be called after Create returns and therefore tnay be 
nested. 

The afterTakenDown is called after the property sheet has been removed from the screen. 
The return parameter of the MenultemProc is ignored in this case. Note: Clients must 
still provide a regular MenultemProc. 

Clients may pass in a zone to be used instead of the default zone" created by the 
StarWindowShell implementation. 

shell is the property sheet. 
nuiiPiace: window.Place; 

nuliPiace defines the default for placement of a property sheet. If the default is used, the 
property sheet is placed at an appropriate place on the screen. 

38.2.2 Menu Items and the MenultemProc 

MenultemType: type = (done, apply, cancel, defaults, start, reset}; 
Menultems: type » packed array MenultemType of BooleanFalseOefault; 
BooleanFalseOefault: type » boolean false: 

propertySheetOefaultMenu: Menultems « [done: true, apply: true, cancel: true],- 
optionSheetDefaultMenu: Menultems a [start: true, cancel: true]: 

The client specifies a set of commands to be placed in the header of the property sheet. 
MenultemType specifies all the possible commands. Menultems specifies a set of these 
commands. It is passed to PropertySheet. Create. propertySheetOefaultMenu and 
OptionSheetDefaultMenu specify two common sets of commands. 

MenultemProc: type = procedure I 
shell: StarWindowSheli.Handle, 
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formWindow: window.Handle, 
menultem: MenuitemType] 

RETURNS [ok: BOOLEAN 4- false] ; 



The client supplies a MenultemProc when a property sheet is created. It is called 
whenever the user selects one of the menu items in the header of the property sheet. 
formWindow is the main form window of the property sheet, menultem is the type of 
menu item that the user selected. The client typically (when the user selects Done or 
Apply) retrieves the values of the items that the user edited (using 
FormWindow.HasChanged and FormWindow.GetXXXitemV/alue procedures), verifies that the 
values are meaningful (for example, that numbers are within proper range), and applies 
the new values to the properties of the object this property sheet represents. 

The return parameter ok has slightly different meanings in the following two cases: 

1. For an ordinary property sheet (not a linked property sheet), the MenultemProc is 
called when the user selects a command and the return parameter indicates whether 
the property sheet should be destroyed. 

2. For a linked property sheet, the MenultemProc is called both when the user selects a 
command in the header (in which the case above applies) and when the client calls 
SwapExistlngFormWindows or SwapFormWindows with apply » true. In this case 
the MenultemProc is called to allow the client to apply any changes made to the form 
window sheet being linked from. The menultem parameter will be "done"; the return 
parameter indicates whether to allow the swap to occur, ok » false indicates that 
something is invalid in the form window and the client does not want the swap to 
occur (the client typically posts a message before returning). If ok « true, the swap 
occurs. 

Note: The client need not worry about these cases when writing the MenultemProc but 
can simply write the "done" code as usual. If the user selects Done and the MenultemProc 
returns ok « true, the property sheet is destroyed. If the user links to another sheet 6n a 
linked property sheet and the MenultemProc returns ok « TRUE, the sheets are swapped, 
rather than the whole property sheet being destroyed. 

38.2.3 Linked PropertySheets 

Several property sheets may be logically linked in the same property sheet. This is 
accomplished by changing form windows within a property sheet's Star window shell and 
having an additional choice item that specifies which form window is currently displayed. 
(See Figure 38.2 below.) 
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Figure 38.2 A Linked Property Sheet 

This additional choice item actually resides in an additional form window called a link 
window. This link window is another body window of the Star window shell. The link 
window remains visible all the time, while the main form window may be swapped. The 
client does this by supplying a FormWindow.ChoiceChangeProc for the single choice item in 
the link window. When the user selects a new choice for that item, the client (in the 
ChoiceChangeProc) calls SwapForm Windows or SwapExistingForm Windows to change 
the main form window. Note: 0^1/3^ one main form window is installed in the Star window 
shell at a time. A linked property sheet is created by calling CreateLinked. 

CreateLinked: proceourc [ 

formWindowltems: Formwindow.MakeltemsProc, 
menultemProc: MenultemProc, 
size: window.DimSr 

menultems: Menultems «- propertySheetDefaultMenu, 
title: xstring.Reader <- NtL« 
placeToDisplay: window.Piace <- nullPlace, 
formWindowltemsLayout:Formwindow.LayoutProc 4- nil, 
windowAttachedTo: starWindowSheii.Handle 4~(nil], 
globalChangeProc: Formwindow.GlobalChangeProc <- nil, 
display: boolean 4-true, 
linkWindowltems: Formwindow.MakeltemsProc, 
linkWindowltemsLayoutrFormvivindow.LayoutProc *- nil, 
clientData: long pointer nil, 
afterlakenOownProc: MenultemProc *- nil. 
zone: uncounted zone*- nil] 

RETURNS [shell: StarWindowSheii.Handle]; 



CreateLinked creates a linked property sheet. Creating a linked property sheet is almost 
identical to creating an ordinary property sheet (see Create above for a full description of 
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all the parameters), except CreateLinked has the additional parameters linkWindowltems 
and linkWindowitemsLayout. linkWindowltems is called to make the choice item in the 
link window. It should create a single choice item with a FormWindow.ChoiceChangeProc. 
linkWindowitemsLayout is called to specify the position of the choice item in the link 
window. The default places the item appropriately in the link window, so most clients will 
want to take the default for linkWindowitemsLayout. Note: formWindowltems and 
formWIndowitemsLayout specify the main form window that is initially visible in the 
property sheet. 

SwapFormWindows: procedure [ 
shell: starWindowSheii.Handle, 

newFormWindowltems: Formwindow.MakeltemsProc, 
newFormWlndowltemsLayout:Formwindow.LayoutProc <- nil, 
apply: boolean <- true, 
destroyOld: boolean true, 
newMenultemProc: MenultemProc ♦-nil, 
newMenultems: Menultems «- all(falS£]. 
newTltle: xstring.Reader 4-nil, 

newGlobalChangeProc: FormWindow.GlobalChangeProc 4-NiL, 
newAfterTakenOownProc: MenultemProc «- nil] 
RETURNS [old: window.Handle]; 

SwapFormWindows swaps the main form window of a property sheet with a new one. It is 
usually called from the FormWindow.ChoiceChangeProc of the choice item in the link 
window. May raise Error [notAPropSheet]. ■""^ 

shell is the property sheet. 

newFormWindowltems supplies the items for the new window. 

newFormWindowltemsLayout specifies the layout for the items in the new form window. 

apply specifies whether any changes to the current form window should be applied before 
the swap. If apply ■ true, the current MenultemProc for shell is called with menultem ■ 
apply. If apply a false, the MenultemProc is not called. 

The destroyOld parameter indicates whether the old form window should be destroyed. If 
destroyOld ■ false, then the return parameter is the old form window, else the return 
parameter is nil. This allows clients to perform the following typical sequence of events: 

1. Create a linked property sheet by using CreateLinked. 

2. The first time the user links to another sheet, call SwapFormWindows with 
destroyOld a false and save the old form window. 

3. When the user goes back to the first sheet, call SwapExistingFormWIndows, 
supplying the previously saved old form window and thus avoiding having to create 
the first form window again. 

newMenultemProc allows the client to install a different MenultemProc than the one that 
was supplied with CreateLinked. 

newAfterTakenOownProc allows the client to install a different takedown MenultemProc 
than the one that was supplied with CreateLinked. 

newMenultems, newTitle, and newGlobalChangeProc allow the client to change these as 
well. 
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If the default newMenuitemProc, newMenultems, newTitle, or newGiobalChangeProc is 

taken, the current values are retained. 

SwapExistingFormWindows: procedure [ 
shell: StarWindowShell.Handle, 
new: window.Handle, 
apply: boolean <- true, 
newMenultemProc: MenulteniProc <-nil, 
newMenultems: Menultems <- all[false], 
newTitle: xstring.Reader «-nil, 
newAfterTakenOownProc: MenultemProc 4-NiLi 
RETURNS [old: Window.Handle j; 

SwapExistingFormWindows swaps the main form window of a property sheet with a new 
one. The new form window must already exist. If it does not, use SwapForm Window, new 
is the new form window, apply, newMenultemProc, newMenultems, and newTitle are the 
same as in SwapFOrmWindow. old is the previous main form window. May raise Error 
[notAPropSheet]. 

38.2.4 Miscellaneous 

GetFormWindows: procedure [shell: starWindowSheii.Handle] 
RETURNS [form, link: window.Handle]; 

GetForm Windows returns the current form windows of shell. If shell is not a linked 
property sheet, link is nil. May raise Error [notAPropSheet]. 

InstaliFormWindow: procedure [ 
shell: starWindowSheiL Handle, 
menultemProc: MenultemProc, 

menultems: Menultems <- propertySheetOefaultMenu, 
title: xstring.Reader <-nil, 
formWindow: Window.Handle, 
afterTakenOownProc: MenultemProc ^-nil]; 

InstaliFormWindow installs formWindow in shell. May raise Error [notAPropSheet]. 

38.2.5 Signals and Errors 

Error: error [code: ErrorCode]; 
ErrorCode: type « {notAPropSheet}; 

Error [notAPropSheet] is raised if a StarWindowSheii.Handle that is not a property sheet is 
passed to a PropertySheet procedure . 
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38.3 Usage/Examples 

38.3. 1 Flow Description of Creating a Property Sheet 

The following describes the sequence of calls involved in creating and taking down a 
property sheet, including ViewPoint interfaces and clients. 

1. Client calls Prop«rtySheet.Create, supplying a FormWindow.MakeitemsProc, a 
FormWindow.LayoutProc (optional), and a PropertySheet. Men ultemProc. 

2. PropertySheet.Create creates a Star window shell and a body window inside the 
StarWindowShell. It then calls FormWindow.Create, passing in the body window. 

3. FormWindow.Create calls the client's FormWindow.MakeitemsProc. 

4. The client's FormWindow.MakeitemsProc creates the items in the property sheet by 
calling various Form window. Ma keXXXI tern procedures. 

5. FormWindow.Create calls the client's FormWindow.LayoutProc. If the client did not 
provide one, a default LayoutProc provided by FormWindow is called. 

6. The FormWindow.LayoutProc makes calls to FormWindow. AppendLine and 
FormWindow. Appendltem to specify the layout of the items created by the 

. FormWindow.MakeitemsProc. 

7. FormWindow.Create returns to PropertySheet.Create. PropertySheet.Create returns to the 
client. The client returns to the Notifier process. 

8. The property sheet is now on the .screen and the Notifier process is waiting for the 
user. 

9. The user changes some values in the property sheet. This is all managed by 
FormWindow; the client gets called only if there is a FormWindow.BooleanChangeProc 
or Formwindow.ChoiceChangeProc or Formwindow.GlobalChangeProc. 

10. The user selects Done in the header of the property sheet. 

11. A procedure inside PropertySheet is called. PropertySheet calls the client's 
PropertySheet.MenultemPrOC. 

12. The client's PropertySheet. MenuitemProc checks for any changed values 
(FormWindow. Has BeenChanged and FormWindow.HasAnyBeenChanged) and calls the 
appropriate FormWindow.GetXXXItemValue to obtain the new values. The client 
validates and applies these new values, and then returns an indication of whether the 
property sheet should be taken down. 

13. PropertySheet takes down the property sheet and returns to the Notifier. 

14. END. 
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38.3.2 An Ordinary Property Sheet 

This example creates a property sheet from some arbitrary properties and then applies the 
user's changes to those properties. It uses a contrived set of properties described by 
Properties and PropertiesObject. In general, a real property sheet would get its properties 
from some real object. This example produces the property sheet shown in Figure 38.1. 

— PropertySheetExample.mesa 

DIRECTORY 

FormWindow using [ 
Choiceltem, GetBooleanltem Value, GetChoiceltem Value, GetTextltemValue, 
HasAnyBeenChanged, HasBeenChanged, ItemKey, MakeBooleanltem, 
MakeChoiceltem, MakeitemsProc. MakeTextitem, SetBooleanitem Value, 
SetChoiceltemVaiue, SetTextltemValue], 

PropertySheet using [Create, MenultemProc], 

StarWindowSheil USING [Handle], 

XString using [FreeReaderBytes, FromSTRING, ReaderBody], 
Window USING [Handle]; 

PropertySheetExample: PROGRAMiMPORTSFormWindow, PropertySheet, XString a { 

Properties: TYPE « long pointer to PropertiesObject; 

PropertiesObject: type ■ record [ 
boolean: BOOLEAN, 
choice: Choices, 
text: xstring.ReaderBody]; 

items: type ■ {boolean, choice, text}; 

Choices: type ■ {choice1,choice2, choice3}; 

zone: uncounted zone 

MakePropertySheet: procedure [props: Properties] 
returns [shell: StarWindowSheii.Handle] « { 
title: xstring.ReaderBody <-xstring.FromSTRING ["Title"L]; 

shell <- PropertySheet.Create [ 
formWindowltems: Makeltems, 
menuitemProc: MenultemProc, 
menultems: [help: true, done: true, cancel: true, 

apply: true, defaults: true], 
size: [w: 300, h: 200], 
title: ©title, 
clientData: props]; 

}; 
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Makeltems: Formwindow.MakeltemsProc ■ { 
props: Properties <-ciientData; 

tag: XString.ReaderBody 4-xstring.FromSTRiNG["Tag"L]; 

BEGIN 

label: xstring.ReaderBody <-xstring.FrofnSTRING["BOOLEAN"L]; 
suffix: xstring.ReaderBody <-xstring.FromSTRING["suffix"L]; 
Formwindow.MakeBooleanitem [ 

window: window, 

myKey: Items.boolean.ORO, 

tag: @tag, 

suffix: ©suffix. 

label: [string [label] ]. 

initBoolean: props.booiean ]; 
end; 

BEGIN 

c1 : xstring.ReaderBody <--xstring.FromSTRING["CHOICE 1"L]; 
c2: xstring.ReaderBody 4- xstring.FromSTRINGC'CHOICE 2"L]; 
c3: xstring.ReaderBody <-xstring.FromSTRlNG["CHOICE 3"L]; 
choices: array [0..3) of Formwindow.Choiceltem «- [ 

[string[Choices.choice1 .ORO, c1 ] ], 

[string[Choices.choice2.0RO/c2] ], 

[string[Choices.choice3.0RO, c3] ] ]; 
Formwindow.MakeChoiceltem [ 

window: window, 

myKey: Items.choice.ORO, 

values: DESCRiPTORfchoices], 

initChoice: props.choice.ORo]; 
end; 

FormWindow.MakeTextltem [ 
window: window, 
myKey: Items.text.ORO, 
tag: @tag, 
width: 40, 

initString: ©props.text]; 

}; 

MenultemProc: PropertySheet.MenultemProc ■ £ 
props: Properties 4- clientData; 
select menultem from 
help ■>...; 

done ■ > RETURN[destroy: AppiyAnyChanges[formWindow,props].ok]; 
cancel « > RETURN[destroy: true]; 

apply ■ > [] 4- ApplyAnyChanges[formWindow, props]; 
defaults > > SetOefaults[form Window, props]; 

ENOCASE a > ERROR; 

RETURN[destroy: false]; 

}; 
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AppiyAnyChanges: proc [window: window.Handle, props; Properties] 

RETURNS [ok: boolean] a BEGIN 

IF -Formwindow.HasAnyBeenChanged [window] then return [ok: true]; 
FOR eachltem: items in Items oo 

itemKey: Formwindow.ItemKey » eachltem.ORo; 

iF -Formwindow.HasBeenChanged [window, itemKey] then loop; 

SELECT eachltem from 

boolean ■ > props.booiean 4—Formwindow.GetBooleanltemValue[window, itemKey]; 
choice > > props.choice 4- VAL[Formwindow.GetChoiceltemValue[ window, itemKey] ]; 
text • > { 

xstring.FreeReaderBytes [r: @props.text, z: zone]; 
props.text 4-FormWindow.GetTextltemValue [window, itemKey, zone]}; 
endcase; 

ENDLOOP; 

return [ok: true]; 
end;- AppiyAnyChanges 

SetDefaults: proc [window: window.Handie, props: Properties] a 

BEGIN 

defauitText: xstring.ReaderBody 4-xstring.FromSTRING["Text item"L]; 
Form window.SetBooieanltem Value [ 

window: window, 

item: Items.boolean.ORO, 

newValue: false]; 
Form window.SetChoiceitem Value [ 

window:, window, 

item: Items.choice.ORO, 

newValue: Choices.choice2.0R0]; 
Formwindow.SetTextltemValue [ 

window: window, 

item: ltems.text.ORO, 

newValue: ©defauitText]; 
end; 

}... 



38-11 



PropertySheet 



38.4 Index of Interface Items 



Item Page 

BooleanFaiseDefault: type 3 

Create: procedure 2 

CreateLinked: procedure 5 

Error: error 7 

ErrorCode: type 7 

GetFormWindows: procedure 7 

InstailFormWindow: procedure 7 

MenultemProc: type 4 

Menultems: type 3 

MenuitemType: type 3 

nullPlace: window.Place 3 

optionSheetDefaultMenu: Menultems 3 

property SheetOefauitMenu: Menultems 3 

SwapExistingFormWindows: procedure 7 

SwapFormWindows: procedure 6 
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39.1 Overview 

Prototype manipulates prototype files. A prototype file is a blank copy of an application's 
file that the user can copy. Prototype files are in the Directory icon under "Blank 
Documents, Folders, etc." 

A prototype file resides in the prototype catalog (see the Catalog interface) and is uniquely 
identified by it is file type, subtype, and version. The subtype distinguishes between 
objects of the same file type, such as the blank document and the basic graphics transfer 
document. Subtype is stored in an e.xtended attribute on the prototype file. A nonexistent 
subtype is equivalent to subtype 0. 

Version is stored in the BWS-standard version extended attribute (see 
BWSAttribute Types). The intent is that clients need only examine the version to 
determine if the prototype is current. A nonexistent version attribute is equivalent to 
version 0. 

Prototype provides Find and Create procedures. A client typically calls Find and if it 
returns NSFiie.nuilReference, then call Create. 

39.2 Interface Items 

Version: type ■ cardinal; 
Subtype: type ■ cardinal; 

Find: procedure [type: NSFiie.Type, version: Version, 

subtype: Subtype <-0, session: NSFiie.Session 4~NSFiie.nullSession] 
RETURNS [reference: NSFiie.Reference]; 

Find returns a reference for the file with the specified type, version, and subtype. If the 
file does not exist, NSFiie.nuilReference is returned. 

Create: PROCEDURE [ 

name: xstring.Reader, 
type: NSFiie.Type, 
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version: Version, 

subtype: Subtype *- 0, 

size: long cardinal «- 0, 

isOirectory: BOOLEAN 4-FALSE, 

session: NSFii«.Session «-NSFiie.nuliSession] 

RETURNS [prototype: NSFiie.Handle]; 

Creates a file in the prototype catalog with the specified name, type, version, subtype, 
size in bytes, and isOirectory attribute. 

Add: PROCEDURE [file: NSFiie.Handle, version: Version, 

subtype: Subtype 4-0, session: NSFiie.Session «- NSFiie.nuilSession]; 

Moves an already existing file into the prototype catalog, assigning it the given version 
and subtype. Fine point: This is in Prototype Extra in ViewPoint. 

PurgeOld Versions: procedure [type: NSFile.Type, current: Version, subtype: Subtype <- 0); 

Deletes any versions of the given prototype that are older (smaller number) than current. 
PurgeOidVersions assumes that higher version numbers are more recent than lower 
version numbers. If this is not true for your version numbers, do not call this operation . 

39.3 Usage/Exampies 

This is an example of a procedure that an application probably calls at initialization time. 

sampieiconFileType: NSFiie.Type « . . . ; 

version: cardinal » 

FindOrCreatelconFlie: procedure « { 

name: xstring.ReaderBody xstring.FromSTRING["Sample lcon"L]; 
- This name should really come from XMessage. 
IF (Prototype.Find [ 

type: sampieiconFileType, version: version] * NSFiie. null Reference) then 
NSFiie.Close [f>rototype. Create [ 

name: @name, type: sampieiconFileType, version: version] ]; 

}; 
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39.4 Index of Interface Items 



Item 


Page 


Add: PROCEDURE 


2 


Create: procedure 


1 


Find: procedure 


1 


PurgeOld Versions: pRoaouRE 


2 


Subtype: type 


1 


Version: type 


1 
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40.1 Overview 

The Selection interface defines the abstraction that is the user's current selection. It 
provides a procedural interface to the abstraction that allows it to be set, saved, cleared, 
and so forth. It also provides procedures that enable someone other than the originator of 
the selection to request information relating to the selection and to negotiate for a copy of 
the selection in a particular format. 

40.1.1 Requestors and Managers 

The Selection interface is used by two different classes of clients. Most clients wish merely 
to obtain the value of the current selection in some particular format; such clients are 
called requestors. These programs call Convert (or ConvertNumber, which in turn calls 
Convert), Query, or Enumerate. These clients need not be concerned with many of the 
detailsof the Selection interface. ' 

The other class of clients consists of those who wish to own or set the current selection: 
these clients are called managers. A manager calls Seiection.Set and provides procedures 
that may be called to convert the selection or to perform various actions on it. The 
manager remains in control of the current selection until some other program calls 
Seiection.Set. These clients need to understand most of the details of the Selection interface. 

The goal of the Selection interface is that the requestor need never know, and should 
never care, what module is managing the selection. All that matters is whether the 
selection can be rendered in a suitable form. For example, suppose the user presses copy 
and selects a printer icon as the destination. The printer implementation needn't know 
what is printable and what isn't. It simply queries the selection to determine whether it 
can be rendered as an Interpress master, and if so, it obtains it and .sends it. Otherwise, it 
queries whether the selection can be enumerated as a sequence of Interpress masters (as 
would be true of a folder, for instance). If this also fails, the object is rejected. 

The selection is the expression of the user indicating the datum to be operated on. As such, 
it is conceptually owned by the user. The selection manager is a slave following the user's 
instructions. 
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To maintain this user interface model, the selection must only be changed at the explicit 
direction of the user. Software must allow the user to change the selection at will. To 
implement this user model, the selection is only changed from within the user process or 
Notifier. The Notifier is the system process that passes the user's actions, encoded as TIP 
results, to application software. 

Software that wishes to read the selection must deal with the fact that the selection may 
be changed at any time that the Notifier process is running. The way to synchronize with 
this potentially asynchronous activity is to only read the selection in the Notifier process. 
This guarantees thai the selection will not be altered while it is being read. Application 
software running in the .Votifier process can be assured that the selection will not change 
until after the application returns to the system. Thus the first rule for dealing with the 
selection is: 

The selection may only be read or changed in the Notifier process. 

Once an application returns to the Notifier, any knowledge it retains about the selection 
may be invalidated at any instant when the user changes the selection. Similarly, if an 
application running in the Notifier passes some information about the selection to another 
process, that information may similarly be invalidated at any time. In these 
circumstances, the application must copy the selection's value, using Copy, Move, or 
CopyMove, to assure that its data remains valid. Thus the second rule for dealing with the 
selection is: 



Copy the selection's value before returning to the system or before passing it to another 
process. 



40.1.2 Essentials for a Requestor 



Clients that need the value of the current selection. 
40.1.2.1 Convert, Target, Value, Enumerate, CanYouConvert 



A selection requestor obtains the value of the current selection by calling Selection. Convert. 
Convert takes a Selection.Target and returns a Selection. Value. The Target specifies what 
TYPE of data the selection should be converted to. The Value contains a pointer to the 
converted selection. For e.xample, Selection.Convert [target: string] returns a pointer to a 
string (an xstring.Reader). 

Not all selections can be converted to all Targets; in fact, most selections can be converted 
to only a small number of Targets. For example, if the selection is a text string, it can be 
converted to Target string and perhaps to integer, but probably not to file or fileType. 
Note: Converting to some Targets is not so much requesting the value of the selection as 
requesting some general information about the selection or its environment. For example, 
Selection.Convert [target: window] is a request for the window that the selection is in, 
Selection.Convert [target: help] is a request for user help information about the 
selection,and so forth. Note that Target is an open-ended enumeration and that clients can 
create new Targets by using Seiection.UniqueTarget. The type associated with each Target 
is determined by system-wide convention. Several of these TYPE/Target conventions are 
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defined below under the description of Target. Other TYPE/Target conventions are 
documented in §40.2.1.1. 

A requestor can also enumerate the selection if it is more than a single item or if it can be 
split into smaller pieces. This is done by calling Selection.Enumerate. 

Finally, a requestor can determine what Targets the selection can be converted to without 
actually doing the conversion by calling Selection.CanYouConvert, Selection. Query, or 
Selection.HowHard. 

40.1.2.2 Resource Allocation/ Deallocation Considerations 

It is a strict rule that the Values produced by Seiection.Convert and Selection.Enumerate 
describe objects owned by the selection manager. The requestor may examine the data 
referenced by the value field but must not alter it. Furthermore, the requestor must free 
the Value (using Selection.Free) once he no longer needs it. 

If the requestor wishes to (1) keep the value after it returns to the system', or (2) pass the 
value to another process, it must call Selection.Copy, Seiection.Move, or Selection. CopyMove. 
These in turn invoke a procedure supplied by the selection manager that modifies the 
Value such that the requestor may then make changes to value f without affecting the 

selection manager. Fine point: The manager returns tiie procedure supplied by the manager as put t of the 
Value record. If a Move is performed, the item is also deleted from the manager's domain. 
After the Move or Copy, any storage associated with the Value is now owned by the 
requestor. This storage may be freed by calling Selection.Free 

For example, if the current selection is a document icon, then Convert[file] yields a Value 
containing a LONG pointer to NSFile.Reference for the file contaming the document. If the 
requestor were to create a new document and associate it with the same file, it would 
probably have undesirable effects. Instead, the requestor should call Copy, passing in 
data:LONG pointer to NSFile.Reference for the destination directory of the new file. When 
Copy returns, the Value contains a reference to a copy of the original file, and the 
requestor can use this freely. 

As a second example, suppose the selection manager uses a Mesa string as the internal 
selection representation. Then Convertlstring] simply builds the string pointer into an 
xstring.Reader using xstring.FromSTRING. If the requestor wants to save the string for very 
long, he should call Copy, and the manager will allocate a copy of the original string using 
the zone passed to Convert. An alternative, somewhat simpler, is for the requestor to call 
xstring.CopyReader or xstring.CopyToNewReaderBody or xstring.CopyToNewWriterBody 
to copy the bytes, and then call Selection.Free to dispose of the original Reader. 

40.1.3 Essentials for a Manager 

Clients that own and manage the current selection. 

40.1.3.1 Set, ConvertProc, ActOnProc, ManagerData 

The implementor of a selection manager needs to know everything that the implementor 
of a selection requestor knows, plus more (see §40. 1.2). 
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The fundamental operation a selection manager performs is to become the current 
manager by calling Setection.Set. Set takes a ConvertProc, an ActOnProc, and a long 
POINTER (ManagerOata). 

The ConvertProc is called to obtain the value of the selection, whenever a requestor calls 
Selection.Convert or Selection.Enumerate. The ConvertProc is also called to determine what 
Targets the selection can be converted to whenever a requestor calls 
Selection.CanYouConvert, Selection.Query, or Selection.HowHard. Conversionlnfo is a variant 
record passed to the ConvertProc that indicates which operation to perform; convert, 
enumeration, or query. 

The ActOnProc is called to perform various Actions on the selection, such as mark, 
unmark, and clear. 

The ManagerOata passed to Set is passed back to the ConvertProc and the ActOnProc. 
Typically, the ManagerOata identifies exactly what portion of the manager's domain is 
currently selected. For example, if the current selection is some text in a document, the 
actual manager is the document application, which has some ManagerOata that indicates 
exactly which characters are currently selected. 

When a manager calls Selection. Set, the previous manager is told to ActOn [clear], and 
Selection forgets about the previous manager. Hence, there is only one selection at a time. 
However, Selection also supports the notion of a "saved" selection. A client can become the 
current manager by calling Selection. SaveAndSet, which does a Set but also saves the 
previous selection. Later, the manager that did the SaveAndSet can do a Selection. Restore, 
which restores the previous selection. 

40.1.3.2 More on Selection. Value, ValueFreeProc, and ValueCopyMoveProc 

The Value produced by a manager's ConvertProc contains more than simply a pointer to 
the converted selection. It also contains a pointer to two procedures, a ValueFreeProc and a 
ValueCopyMoveProc. The ValueFreeProc is called when the requestor calls Selection. Free so 
that the manager can release any resources that were allocated when the selection was 
converted. The manager's ValueCopyMoveProc is called when the requestor calls Copy, 
Move, or CopyMove. The ValueCopyMoveProc should copy or move the converted 
selection value so that the manager no longer owns the resources associated with the 
value. A third Held in the Value record is a long unspecified that may be used to store data 
for the ValueFreeProc and the ValueCopyMoveProc. 

If the converted .selection value can be copied or moved, the manager must return a 
ValueCopyMoveProc with the Value. For example, Targets string and file can be moved or 
copied, while it does not make sense to move or copy Targets window and filelype. The 
ValueCopyMoveProc modifies the Value such that the requestor may then make changes 
to value I without affecting the selection manager. If a Move is performed, the item is 
also deleted from the manager's domain. (Some managers may implement Copy but raise 
Error[invalidOperation] if asked to do a Move.) The interpretation of the data given to a 
ValueCopyMoveProc depends on the manager; the typical use is to specify a destination 
for the object. 
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40.1.3.3 Storage Considerations for ConvertProc 

As stated above, it is a strict rule that the Values produced by the ConvertProc describe 
objects owned by the manager. If the manager allocated any resources to produce the 
converted selection value, then a ValueFreeProc must be returned with the Value so that 
the resources can be released. If a VaiueCopyMoveProc was returned with the Value, after 
the converted selection value has been copied or moved, the manager must ensure that the 
correct things happen when the Value's ValueFreeProc is called (that is, when the 
requestor calls Seiection.Free). This may involve replacing the original ValueFreeProc. 

The manager's ConvertProc takes a zone that Selection guarantees is valid (except for the 
query operation). The manager should allocate any storage for the converted selection 
value from that zone. The ConvertProc can store the zone in the context (long unspecified) 
field of the Value record (or in a record pointed to by the context field). The ValueFreeProc 
and VaiueCopyMoveProc can then retrieve this zone to free the storage. 

Selection provides numerous defaults to ease the manager's task of proper storage 
management. In practice, the ConvertProc can simply default the context field and 
Selection will place the zone there. Also, procedures such as FreeStd and FreeContext 
perform the loopholes, free the storage and store null and/or no-op values such as NopFree 
in the Value record. 

40.1.3.4 Storage Considerations for ManagerData 

The ManagjerOata that identifies exactly what part of the manager's domain is currently 
selected should be allocated whenever a Selection.Set is done and deallocated whenever 
ActOn [clear] is requested. In particular, a manager should not assume that only one 
selection at a time is in its domain. The existence of SaveAndSet and Restore implies that 
the same manager code could have several pushed selections at once and therefore would 
have several ManagerOata records allocated at once. 

40.2 Interface Items 

40.2.1 Requestor items 

40.2.1.1 Convert 

Convert: procedure [target: Target, zone: uncounted zone nil] 
RETURNS [value: Value] ; 

Value: type * record [value: long pointer, . . .]; 

nullValue: Value ■ [value: nil, . . .]; 

Convert is a request to the current selection manager to produce the selection as a type 
specified by target, if possible, value.vaiue is a long pointer to the converted selection. The 
TYPE of object pointed to by value.vaiue depends on target and is described below under 
Target. If the conversion requires that storage be allocated, it is allocated out of zone. If 
zone is defaulted, the system heap is used. 
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The value returned is read-only; it belongs to the manager. If the requestor wishes to (1) 
keep the value after it returns to the system or (2) pass the value to another process, it 
must call Copy, Move, or CopyMove to make a copy of the value, which is then owned by 
the requestor. If Copy, Move, or CopyMove is called, the requestor must still call Free. 

If Copy, Move, or CopyMove is not called, the requestor must call Free after calling 
Convert. This allows the manager to free any resources that were allocated to perform the 
conversion. If Copy, Move, or CopyMove is called, the requestor then owns any resources 
and may retain them indefinitely, may free them, or both, by calling Free. 

The requestor need not be concerned with the other fields in the Value record. They are 
described in the section on manager items . 

nullValue is returned if the selection manager does not implement the desired conversion 
or if the particular selection is incompatible with the target (such as Convert[integer] 
when non-numeric characters are selected). 

Target: type ■ machine depenoent{ 

window(O), shell, subwindow, string, length, position, 
integer, interpressMaster, file, filelype, token, help, 

interscriptScript, interscriptFragment, serializedFiie, name, flrstFree, last<1777B)}; 

Target describes the type of data to which a selection may be converted (see Convert). 
Modules that manage the current selection may choose not to implement conversion to 
some (or even most) of these types. The values described below are those stored in the 
value field of the S«iection.Value returned by Convert. 

Special note for Targets that produce a Stream. Handle: The stream. Object pointed to by the 
Straam.Handle is read-only. Thus the requestor cannot even read the stream because that 
alters the stream state and thus the stream. Object. Before using the stream, the requestor 
must do a Copy, after which the ownership of the storage for the stream. Object and any of 
its ancillary data moves to the requestor. iVote also that the stream itself is read-only even 
after the Copy. The requestor should never attempt to write to the stream. After reading 
the stream, the requestor can free the stream and any associated resources by calling 
stream. Delete. Thus a typical stream requestor will do Convert(stream]; CopyH; <read 
stream >; stream. OeleteH; Note for selection managers: this last point means that the 
stream. Delete must be able to free any ancillary data associated with the stream. 

Some Target values refer to types that are not defined within the context of ViewPoint. 
Such targets so far include pieceList, help, InterscriptScript, and InterscriptFragment. 
Popular target types are included in the Selection interface as a convenience for clients. 
New target types will be put either into a Selection Extras interface or, for little-used types, 
into private interfaces negotiated between managers and requestors and using 
Selection.UniqueTarget. The type associated with each Target is determined by system-wide 
convention. Several of these' TYPE/Target conventions are defined here. Other TYPE/Target 
conventions are documented elsewhere. (See §40.2.2.8). 

Fine point: This Selection interface is intended to support botli XDE and ViewPoint clients, so tiiere may be 
Targets ttiat do not make sense in one domain or the other. Targets that only make sense in one domain show that 
domain in parentheses. 



window 



Yields a window.Handle for the window containing the selection. 
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shell 

subwindow 
string 



length 
position 
pieceList 
integer 

interpressMaster 
file 



fiieType 



token 



help 



interscriptScript 



Yields a starWindowSheil.Handle for the window containing the 
selection. (Viewpoint) 

Yields a window.Handle for the subwindow containing the 
selection. (XOE) 

Yields a long pointer to xstring.ReaderBody (an xstring. Reader) 

representing the te.xt of the selection. If the current selection is 
too large, the manager of the selection may return nullValue 
when asked to convert to a string. The requestor should then ask 
to enumerate the selection as a sequence of smaller strings. Note: 
The requestor must copy the ReaderBody before altering it. 

Yields a long pointer to long cardinal containing the length of 
the selection in characters. 

Yields a long pointer to long cardinal containing the position 
within the source. 

Yields a list of pieces, understood by the internals of XDE's 
PieceSource interface. (XDE) 

Yields a long pointer to long integer containing the result of 
converting the contents of the selection to a number. 

Yields a Stream.Handle -onto an Interpress master, according to 
the Interpress standard. 

Yields a LONG pointer to NSFHe.Reference for the file (if any) 
associated with the selection, such as the backing file for a Star 
document icon. When calling Copy, Move, or CopyMove, the 
data parameter must be a long pointer to NSFHe.Reference of the 
parent directory to where the file should be copied or moved. 
After calling Copy, the vaiue.vaiue is replaced by a long pointer 
TO NSFHe.Reference of the newly copied file. (Viewpoint) 

Yields a long pointer to NSFile.Type for the file (if any) associated 
with the selection. (Viewpoint) 

Yields a long pointer to xstring.ReaderBody (an xstring. Reader) 

that contains the first token of the current selection. Note: The 
requestor must copy the ReaderBody before altering it. 

Yields a long pointer to a value or data structure that specifies 
what should happen if the HELP key is pressed. Consult the Help 
documentation (not in this manual) for the exact TYPE. 

Yields a Stream.Handle onto a complete script, according to the 
Interscript standard. It begins with the "Interscript 1.0 . . and is 
in machine code. 
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interscriptFragment Yields a Stream.Handle onto a single Interscript node, in machine 
code. 

serializedFlie A Target of serializedFile results in a Stream.Handle. 

Stream.GetXXX operations can be performed on the stream. This is 
useful for retrieving Hies from non-NSFile mediums such as a 
floppy disk. 

name A Target of name results in a xstring. Reader that contains the 

name of the object. 

firstFree Is used internally by UniqueTarget and should not be used by 

clients. 

ConvertNumber: procedure [target: Target] 

RETURNS [ok: BOOLEAN, number: long unspecified]; 

This procedure lets the requestor streamline code in many cases. ConvertNumber calls 
Convert and assumes that the resulting value.value references a 32-bit object. (This is 
true of the targets length, position, integer, and fileType and may also be true of targets 
defined using UniqueTarget.) The object is returned as number, and the Value is then 
freed (Seiection.Free). If the selection manager does not support the desired conversion (that 
is, if it returns nullValue) or if the selection could not be qonverted to a number, 
ConvertNumber returns ok:FALSE; otherwise, it returns ok:TRUE. 

Free: procedure [v: VaiueHandle]; . 

ValueHandie: type a long pointer to Value; 

Free allows the manager to free any storage associated with v. Free should always be 
called after calling Convert (but if Copy or Move is going to be called, do not call Free until 
after calling Copy or Move). Fine point: after calling Copy or Move. Free is a no-op because the manager 
should have handed over any storage ownership to the requestor. It is easier tor the requestor to simply 
remember the rule, "Always call Free," The manager takes care of ensuring that an extraneous Free is harmless. 

40.2.1.2 Query 

A requestor can determine exactly which Targets the current selection can be converted to 
and how difficult the conversion would be. The most common way to do this is 
CanYouConvert, which takes a Target and returns a boolean indicating whether the 
selection can be converted to that Target. HowHard is similar to CanYouConvert but 
returns a Difficulty. Query allows a requestor to determine the Difficulty of conversion for 
an array of Targets. 

Note: For all these queries, the manager is indicating how hard it would be to attempt to 
convert the selection to that target type. Attempt is a key word. The manager might be 
willing to attempt to convert the selection to an Interpress master and yet run out of disk 
space when the conversion is actually requested. Likewise, the manager might support 
conversion to integer, but the conversion could fail if the selection contains invalid 
characters. 
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CanYouConvert: procedure [target: Target, enumeration: boolean <- false] 
RETURNS [yes: boolean] ■ inline { 

RETURN [ HowHard [ target, enumeration ] # impossible ] }; 

CanYouConvert determines whether the selection manager supports conversions to the 
specified target, enumeration a true means the requestor wants to know if the manager 
supports enumerating the selection in the specified target form. (See the section on 
Enumeration below.) 

HowHard: procedure [target: Target, enumeration: boolean «- false] 
RETURNS [difficulty: Difficulty]; 

Difficulty: type ■ {easy, moderate, hard, impossible}; 

HowHard determines the difficulty the selection manager would have attempting to 
convert to the specified target, enumeration ■ true means the requestor wants to know 
the difficulty of enumerating the selection in the specified target form. (See the section on 
enumeration below.) 

The difficulty ratings are interpreted roughly as follows: 

easy Requires virtually no computation (other than allocating 

storage for the Value). Example; length when the selection is 
being maintained as two character indices within a string. 

moderate Requires some amount of computation but nothing outrageously 
time-consuming. Example: converting the above-mentioned 
substring representation to a string or integer target. 

hard Requires extensive computation. Example: interpressMaster. 

impossible The selection manager does not support this conversion. 

Query: procedure [targets: long descriptor for array of QueryElement]; 

QueryEiement: type ■ record [ 
target: Target, 

enumeration: boolean 4- false, 
difficulty: Difficulty <- trash]; 

Query allows a requestor to determine the difficulty of conversion for several Targets. The 
requestor should construct the ARRAY OF QueryElement, filling in target and enumeration 
for each QueryElement. The manager then stores a Difficulty in each QueryElement 
indicating how hard it would be to attempt to convert the selection to that target. The 
requestor can examine the difficulty field of each QueryElement after the call to Query. 

40.2.1.3 Enumeration 

The selection is sometimes a collection of items (for example, several rows of a folder) or a 
single large item that can be split up (for example, a long string can be broken into several 
smaller ones). A requestor can request that each item or part of such selections be 
converted to some Target by calling Seiection.Enumerate. Enumerate is logically similar to 
calling Convert for each item, and the same storage ownership rules apply (see Convert) 
Not all selection managers support enumerating the selection; for e.xample, they do not 
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support a selection that is more than one item. Often a requestor calls Convert and, if that 
fails (returns nullVaiue), calls Enumerate. 

Enumerate: procedure [ 

proc: EnumerationProCr target: Target, data: RequestorOata 4- nil, 
zone: UNCOUNTED ZONE 4- nil] 
RETURNS [aborted: boolean]; 

EnumerationProc: type ■ procedure [element: Value, data: RequestorOata] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

RequestorOata: type ■ long pointer; 

Enumerate is a request to the selection manager to enumerate the current selection, 
converting each element to target, proc is called for each element, data is passed back to 
proc each time it is called. As with the Value returned by Convert, the requestor must 
consider each element to be read-only until Copy, Move, or CopyMove is called, and the 
requestor must free the value by calling Free for each element. Free allows the manager 
to free any storage associated with element. Free should always be called for each element 
(but if Copy or Move is going to be called, do not call Free until after calling Copy or 

Move). Fine point: after calling Copy m Move. Free is a no-op because the manager should have handed over 
any storage ownership to the request<*r It i«i easier for the requestor to simply remember the rule. "Always call 
Free." The manager takes care of ensuring that an extraneous Free is harmless. 

Stop is returned from proc by the requestor and indicates whether the enumeration should 
be stopped^ aborted indicates whether the enumeration completed normally or terminated 
prematurely. 

If the manager cannot convert the selection to the target type or if the manager does not 
implement enumeration, proc is not called. 

Warning: the requestor must not do anything inside of proc that would cause Selection to 
be called (Clear, for example) because this results in a monitor lock. 

Reconversion: SIGNAL [ 
target: Target, zone: uncounted zone] returns [Value]; 

ReconvertOurlngEnumerate: procedure [ 
target: Target, zone: uncounted zone <- nil] returns [Value]; 

A requestor may wish to reconvert the current item during an enumeration of the 
selection. The requestor should call ReconvertOuringEnumerate, which raises the signal 
Reconversion. If the manager supports reconversion, it should catch the signal and return 
the reconverted value. If the manager does not support reconversion, it should ignore the 
signal. Enumerate catches the signal and returns nuliValue. ReconvertOuringEnumerate 
acts like Convert with respect to zone. 

maxStringLength: cardinal 

maxStringLength is obsolete. 
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40.2.1.4 Copy» Move, Free, etc. 

The Values produced by Convert and Enumerate are strictly read-only. The storage is 
owned by the manager. The requestor may examine the data referenced by the value field 
but must not alter it. 

If the requestor wishes to (1) keep the value passed when it returns to the system, or (2) 
pass the value to another process, it must call Copy, Move, or CopyMove. These in turn 
invoke a procedure supplied by the selection manager that modifies the Value so that the 
requestor may then make changes to value.valuef without affecting the selection 
manager. Pine point: This procedure is returned by the manager as part of the Value record, but the requostor 
never needs to know about these details. If a Move is performed, the item is also deleted from the 
manager's domain. After the Move or Copy, the requestor owns any storage associated 
with the Value. This storage may be freed by calling Free, 

For example, if the current selection is a document icon, then Gonvert[file] yields a Value 
containing a long pointer to NSFile. Reference for the file containing the document. If the 
requestor were to create a new document and associate it with the same file, it would 
probably have undesirable effects. Instead, the requestor should call Copy, giving it a long 
POINTER TO NSFile.Reference for the destination directory of the new file. When Copy 
returns, the Value contains a reference to a copy of the original file, and the requestor can 
use this freely. Furthermore, whereas calling Free with the original Value might have 
deleted the file (because the file then belonged to the manager, who might have created it 
solely for the Convert request), calling Free for the new Value frees only the 
NSFile.Reference storage (because the file is now a permanent object belonging to the 
requestor). 

Copy: PROCEDURE [v: VaiueHandle, data: long pointer] * inline { 
CopyMove(v, copy, data]}; 

Move: procedure [v: ValueHandle, data: long pointer] ■ inline { 
CopyMove[v, move, data]}; 

CopyMove: ValueCopyMoveProc; 

ValueCopyMoveProc: type a procedure [ 

v: ValueHandle, op: CopyOrMove, data: long pointer]; 

CopyOrMove: type ■ {copy, move}; 

Copy, Move, and CopyMove request the manager to make a copy of the converted 
selection value (v.value 1 ) and, for Move, also delete the selection from the manager's 
domain. A requestor may call these procedures after calling Convert or from an 
EnumerationProc while doing an Enumerate, data is passed to the manager; what it points 
to depends on the particular Target, data often points to a destination container for the 
copied value. For example, for Target file, data is a long pointer to NSFile.Reference for the 
destination directory. The exact meaning of data for each target is specified in the 
description of that target under Target above. Copy, Move, and CopyMove may raise 
Error [invalldOperation]. 
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40.2.2 Manager Items 



40.2.2.1 Set 

Set: PROCEDURE [pointer: ManagerOata, conversion: ConvertProc, actOn: ActOnProc]; 
ManagerOata: TYPE ■ long pointer; 

The Set procedure allows a client to become the manager of the current selection by 
supplying the Selection interface with a pair of procedures. The ActOnProc is called to 
modify or manipulate the current selection. The ConvertProc is called to get the value of 
the current selection. The value of pointer passed to Set is used as the data argument in 
calls to conversion or actOn. pointer typically points to a record that describes what part 
of the manager's domain is currently selected. If there is already a selection manager 
when Set is called, Set first calls that manager with ActOn[unmari<] and ActOn[clear]. Set 
automatically calls the new ActOnProc with an action of marie. 

Either conversion or actOn can be explicitly nil. If conversion is nil, then Convert always 
returns nultValue, Enumerate is a no-op, and Query will always respond impossible. If 
actOn is nil, then ActOn is a a no-op for all actions. 

ConvertProc: type ■ procedure [ 
data: ManagerOata, 
target: Target, 
zone: uncounted zone. 
info: Conversion! nfo *- [convertHl ] 
returns [value: Value]; 

Conversion! nfo: type » record [select type: *from 
convert » > null, 

enumeration » > [proc: procedure [Value] returns [stop: boolean]], 
query • > [query: long descriptor for array of Query Element], 
endcase]; 

A ConvertProc is provided by a manager when becoming the manager (that is, when 
calling Set or SaveAndSet). The manager's ConvertProc is called when a requestor calls 
Convert, Enumerate, or Query. The ConvertProc should perform the conversion, the 
enumeration, or the query, info is a variant record indicating which operation to perform; 
it contains data appropriate to each operation. The ConvertProc should use with info 
SELECT to determine which operation is requested. Each operation is described in detail in 
the following sections, data is the pointer that was passed to Set or SaveAndSet and 
typically points to a record that describes what part of the manager's domain is currently 
selected, target indicates the type of object that the selection should be converted to and is 
meaningful only for conversion and enumeration, zone should be used to allocate any 
storage for the converted selection value. It is meaningful only for conversion and 
enumeration. 

ActOnProc: TYPE > procedure [data: ManagerOata, action: Action] 
RETURNS [cleared: boolean 4- false]; 



40-12 



Viewpoint Programmer's Manual 



40 



The manager of the selection provides an ActOnProc to perform various actions on the 
selection. ActOnProc is fully described later in this chapter. 

40.2.2.2 Conversion 

Conversion! nfo: TYPE « record [select type: *from 
convert ■ > null, 

enocase]; 

Value: type « record [ 
value: long pointer, 
ops: LONG pointer to ValueProcs «- nil, 
context: long unspecified 4-0]; 

Convert calls the manager's ConvertProc with convert Conversionlnfo to perform the 
requested conversion. The ConvertProc returns a value: Value. If the conversion can be 
performed, value.value should point to the converted selection value; value.ops should 
point to a pair of procedures, a ValueFreeProc that releases any resources that were 
allocated to perform the conversion and a ValueCopyMoveProc that copies or moves the 
converted value, value.context can be used to save any information that the pair of 
procedures might need, (value.ops and value.context are described in detail later ) If the 
manager does not support the requested Target or there is some problem with the 
conversion, the ConvertProc should return nullValue. (See Target for the effect of different 
conversion targets.) 

If the conversion requires that an object be allocated, the ConvertProc should allocate it 
out of zone. If the requestor passed a nil zone to Convert, Convert passes the system zone 
to ConvertProc. The ConvertProc can assume that it is always given a valid zone. 

40.2.2.3 Query 

Conversionlnfo: type ■ record [select type: * FROM 
• • •# 

query m > [query: long descriptor for array of QueryElement], 
endcaseI; 

QueryElement: type * record [ 
target: Target, 

enumeration: boolean <~ false, 
difficulty: Difficulty «- trash]; 

Query, HowHard, and CanYouConvert call the manager's ConvertProc with query 
Conversionlnfo. The ConvertProc should examine the target and enumeration fields of 
each QueryEiement (these were filled in by the requestor) and fill in the difficulty field 
indicating how hard it would be to attempt to convert the selection to that target 
(enumeration « false) or to convert the selection to an enumeration of that target 
(enumeration « true). 

All managers are expected to implement queries; the assumption is that most difficulty 
ratings can be determined simply by indexing into a constant array. The Value actually 
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returned by the ConvertProc in response to a query is ignored; nuliValue or trash may be jgiii 
returned. 

Note that the manager is indicating how hard it would be to attempt to convert the 
selection to that target type. Attempt is a key word. The manager might be willing to 
attempt to convert the selection to an Interpress master and yet run out of disk space when 
the conversion is actually requested. Likewise, the manager might support conversion to 
integer, but the conversion could still fail if the selection contains invalid characters. 

40.2.2.4 Enumeration 

Conversioninfo: TYPE a record [select type: *from 
• • • » 

enumeration ■ > [proc: procedure [Value] returns [stop: boolean]], 
■ • • » 

endcase]; 

Enumerate calls the manager's ConvertProc with enumeration Conversioninfo. The 
ConvertProc should convert each element or part of the selection according to target and 
call proc for each element. The Value passed to proc is just as it is for conversion (see the 
section on Conversion above and the following section). If proc returns stop ■ TRUE, the 
ConvertProc should stop the enumeration and return. The Value returned by the 
ConvertProc after an enumeration is ignored; nullValue or trash may be returned. Not all 
selection owners are expected to implement enumerations: if an enumeration is requested 
and not supported, the ConvertProc should simply return and take no other action. Fine 
point: The ConvertProc does not cull the requestor's EnumerationProc Jirectly: rather, proc is inside Enumerate 
and Enumerate calls the requestor's EnumerationProc. This lets Enumerate insert the zone into the 
Value.context if it is zero, just as Convert does for Values produced by a simple conversion. 

maxString Length: cardinal a . . . ; 

maxString Length is obsolete. 

40.2.2.5 Free, Copy, Move, etc. 

ValueHandle: TYPE ■ long pointer to Value; 

Value: type * record [ 
value: long pointer, 
ops: long pointer to ValueProcs nil, 
context: long unspecified <- 0] ; 

The selection manager provides the value of the selection or other selection-related 
information to the requestor by means of Value records. These records are typically either 
returned by a ConvertProc or passed as elements to the requestor's EnumerationProc. The 
ops field defines the effect of Free, Copy, Move, and CopyMove. The context field may be 
used to store data for use by the ops procedures. If the context field is defaulted (zero) by 
the selection manager, Selection stores the zone that was passed to the ConvertProc there 
before the Value is handed to the requestor. 
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ValueProcs: type ■ record ( 
free: ValueFreeProc <- nil, 
copyMove: ValueCopyMoveProc *- nil]; 

ValueProcs are returned by the manager as part of a Value record. If the manager 
allocated any resources to produce the converted selection value, then a ValueFreeProc 
must be returned with the Value so that the resources can be released, free is called when 
the requestor calls Free. If the converted selection value can be copied or moved, the 
manager must return a ValueCopyMoveProc with the Value. For example, Targets string 
and file can be moved or copied, while it does not make sense to move or copy Targets 
window and fileType. copyMove is called when the requestor calls Copy, Move, or 
CopyMove. 

40.2.2.5.1 Free 

ValueFreeProc: type ■ procedure [v: ValueHandle]; 

If any resources were allocated to produce the converted selection value, they should be 
released in the manager's ValueFreeProc. The ValueFreeProc is returned as part of the ops 
field of a Value. The ValueFreeProc is called when the requestor calls Free, v points to the 
Value that represents the converted selection. 

Defaults are provided such that for the most common case when the ConvertProc simply 
allocates one node of storage from the passed zone, the manager need not supply a 
ValueFreeProc. Selection takes care of freeing the storage when the requestor calls Free. 
The details of how this works are as follows: 

The manager's ConvertProc takes a zone that Selection guarantees is valid. The manager 
should allocate any storage for the converted selection value from that zone. The 
ConvertProc can store the zone in the context field of the Value record (or in a record 
pointed to by the context field); then the ValueFreeProc can retrieve this zone to free the 
storage. Selection stores this zone in the context field if context is zero (the default) in the 
Value returned by the ConvertProc (or passed to the EnumerationProc). v.value points at 
the converted selection object to be freed. Now, Free calls FreeStd if the Value passed to 
Free has ops ■ nil or ops.free « nil. FreeStd treats v.context as a zone and calls 
v.context.FREE[@v.value]. 

If no resources should be freed (for example, after Convertlwindow]), the selection 
manager should use NopFree as the ValueFreeProc. (See also nopFreeValueProcs.) 

FreeStd: ValueFreeProc; 

FreeStd assumes the resources of the Value can be freed by treating v.context as a zone 
and calling v.context.FREE[(@v.value]. If a Value has ops a nil or ops.free « nil, Free will 
call FreeStd. 

NopFree: ValueFreeProc; 

The NopFree procedure should be used as the ops.free for a Value involving no temporary 
resources owned by the selection manager. Thus, a Value created by Convertlwindow] 
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would probably use NopFree, as would Converttstring] if the Valueovalue pointed to a 
permanent xstring.ReaderBody belonging to the manager. (See also nopFreeValueProcs.) 

40.2.2.5.2 Copy and Move 

ValueCopyMoveProc: type « procedure [ 

v: ValueHandle, op: CopyOrMove, data: long pointer]; 

CopyOrMove: type « {copy, move}; 

The manager's ValueCopyMoveProc is called to copy or move the converted selection 
value. A ValueCopyMoveProc is returned by the manager's ConvertProc as part of the ops 
field of a Value. The ValueCopyMoveProc is called when the requestor calls Copy, Move, 
or CopyMove. The ValueCopyMoveProc should modify the Value so that it no longer 
involves any manager-owned storage. If a Move is performed, the item is also deleted from 
the manager's domain. (Some managers may implement Copy but raise 
Error[lnvalidOperation] if asked to do a Move.) data is the data parameter that the 
requestor passed to copy or move. It is often a pointer to the destination container for the 
copied value. The interpretation of data depends on the Target; it is specified in the 
description of each target under Target above, v points to the Value representing the 
converted selection, op indicates whether to do a copy or move. Note: v.context can be 
used by the manager to save information between the ConvertProc and the 
ValueCopyMoveProc. 

The ValueCopyMoveProc should release (or perhaps simply turn over control of) any 
resources that were allocated by the ConvertProc to produce the original converted value. 
Conceptually, the ValueCopyMoveProc makes a copy of the converted value and then 
releases any resources that were used to produce the original converted value. If the 
original converted value itself was a copy produced by the conversion process, this effect 
might be achieved by doing nothing — the requestor just becomes the owner of the copy. 

If the converted value can only be copied once (the typical case), the ValueCopyMoveProc 
should also set v.ops.copyMove to nil to prevent the manager's ValueCopyMoveProc from 
being called again. If the requestor does call Copy or Move again. Selection raises Error 
[invalidOperation]. 

The ValueCopyMoveProc should also ensure that v.ops.free and v.context have 
appropriate values so that when the requestor calls Free, the right thing happens. For 
example, if the newly copied selection was allocated from a zone, v.ops.free should free it 
from that zone (see ValueFreeProc and FreeStd); or if the newly copied selection has no 
storage allocated for it, v.ops.free should be NopFree. 

nopFreeValueProcs: readonly long pointer to ValueProcs; - ©[NopFree, nil] 

This is provided for use as the ops vector in Values that require no temporary storage and 
that cannot be moved or copied. The window and subwindow Targets typically produce 
such values. 

FreeContext: procedure [v: ValueHandle, zone: uncounted zone] ■ inline { 

ZOne.FREE[LOOPHOLE[@V.COntext, LONG POINTER TO LONG POINTER]]; 

V.context 4-LOOPHOLE[zone]}; 
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When the requestor calls Copy or Move, the manager's ValueCopyMoveProc is expected 
"furn^^ to modify the Value so that it no longer involves any manager-owned storage. If the 

manager has been using the context field as a pointer to additional private data, this 
private data must be freed. It would normally require merely a zone.FREE[@v.context]; 
however, because the context is a long unspecified, a loophole is needed. FreeContext hides 
this LOOPHOLE from the Implementor and does the required zone.FREE. It also stores the 
zone in place of v.context, for possible later use by FreeStd. 

40.2.2.6 ActOn 

ActOnProc: type ■ procedure [data: ManagerOata, action: Action] 
RETURNS [cleared: boolean false]; 

An ActOnProc is provided by the manager of the selection to perform various actions on 
the selection, data is the pointer that was passed to Set or SaveAndSet and typically points 
to a record that describes what part of the manager's domain is currently selected, action 
indicates what action to perform (see Action below). An ActOnProc should return cleared: 
TRUE if the action resulted in the selection being cleared; that is, if the manager is no 
longer responsible for the selection. (This should always be the case for action: clear and 
may also occur for delete or clearlfHaslnsert.) 

Action: TYPE ■ machine oepenoent{ 

ctear(O). mark, unmark, delete, clearlfHaslnsert, save, restore, firstFree, last(255)}; 

Unselects the current selection by freeing any associated 
private data, undoing TIP notification changes, and so forth. 

Highlights the current selection. If it is already highlighted, 
this is a no-op. 

Dehighlights the current selection. If it is not already 
highlighted, this is a no-op. 

Deletes the contents of the current selection. The selection 
manager may decide against deleting it. 

clearlfHaslnsert Same as unmark plus clear, but only if the insertion point 
(input focus) is in the selection. This action is used when a 
secondary selection has been completed (for copy-from); if the 
place to which the secondary selection is to be copied (the 
insertion point) is within the selection itself, the selection is 
cleared after its contents are obtained and before the insertion 
takes place. 

save Unselects the current selection but does not necessarily free 

any associated private data, because the selection is expected 
to be restored later. This action will often be a no-op, but the 
manager might need to undo a special TIP notifier, for example. 

''HM^'' restore Restores a previously saved selection. 



clear 



mark 



unmark 



delete 
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firstFree Is used internally by UniqueAction and should not be used by 

clients. 

Observe that, contrary to the interpretations used in the XDE Selection interface, the 
clear action does not dehighlight the selection. Selection.Clear (usually) does an explicit 
unmark before clearing the selection. Likewise, save does not imply unmark, nor does 
restore imply mark. This lets a client choose to leave a primary selection highlighted 
while a secondary selection is being made. 

40.2.2.7 Save and Restore 

SaveAndSet: procedure [ 

pointer: ManagerOata. conversion: ConvertProc, actOn: ActOnProc, 
unmark: boolean 4-true1 
RETURNS [old: Saved]; 

SaveAndSet is the same as Selection.Set except that the existing selection, if any, is told to 
ActOn[savel rather than ActOn[clear] (that is, the existing selection is expected to retain 
any private state so that it can later be restored via Selection. Restore). If it subsequently 
turns out that the saved selection is never going to be restored, it should be given to 
Selection.Oiscard so that the former selection manager has a chance to discard any 
associated private data. A saved selection must always be given eventually to either 
Restore or Discard; furthermore, once that has been done, the Seiection.Saved must not be 
used for anything else. 

It is perfectly acceptable to call SaveAndSet when there is no selection. If the resulting 
Seiection.Saved is passed to Selection. Restore, it acts like Selection.Clear. Also, unlike for 
Clear, ClearOnMatch, and Restore, it is quite reasonable to call SaveAndSet with unmark: 
FALSE, thereby requesting that the saved selection remain highlighted while a secondary 
selection is performed. If this is done, the caller usually wishes to specify mark: false when 
the saved selection is restored. Note: Calling SaveAndSet with unmark: false does not 
necessarily mean that the old selection is marked. The selection manager or some other 
client might have unmarked it. The present caller is simply saying, "Do not change the 
highlighting on my account," but has no way of knowing whether the saved selection is in 
fact highlighted. That is why it is always up to the selection manager to decide whether 
ActOn[mark] or ActOn[unmark] is a no-op. 

Saved: type [6]; 

Objects of this type are created by Selection. SaveAndSet to encapsulate a selection that is to 
be restored later. It is opaque to prevent requestors from invoking the manager directly. 

Restore: procedure [saved: Saved, mark, unmark: boolean 4-true]; 

This procedure re-institutes a previously saved selection as the current manager. The 
existing selection, if any, is requested to ActOn(unmarkl (unless unmark is false; see 
Selection.Clear) and then ActOn[clear]. The selection being restored is asked to 
ActOn[restore] and then ActOn[mark] (unless mark is false). 

Discard: procedure [saved: Saved, unmark: boolean «-true]; 
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If a client, having saved somebody else's selection (see SaveAndSet), determines that it 
should never be restored, the client should call this procedure to free the associated 
resources. The current selection is not affected. The ActOnProc of the saved selection is 
called with action: unmark (unless unmark is false; see Clear) and again with action: 
clear. Thus the ActOnProc must be prepared to handle these operations while the 
corresponding selection is saved. 

40.2.2.8 Miscellaneous 

Clear: procedure [unmark: boolean 4-true]; 

The Clear procedure requests that the curi"ent selection be cleared. It is equivalent to 
calling ActOn[clear], preceded by ActOh[unmarkJ if unmark is true. The only time unmark 
should be false is if the caller knows the area of the screen containing the selection is 
going to be repainted soon anyway; for example, if the window containing the selection is 
going away. 

ClearOnMatch: procedure [pointer: ManagerOata, unmark: boolean oTrue]; 

It is sometimes difficult to determine if you are the manager of the current selection. The 
ClearOnMatch procedure is the same as Clear except that no action is taken unless pointer 
matches the ManagerOata of the current selection. ClearOnMatch is equivalent to if 
Seiection.Match[pointer] THEN Seiection.Clear[unmark]. 

ActOn: procedure [action: Action]; 

The ActOn procedure communicates a request for an action to the manager of the current 
selection. (See also UniqueAction.) Calling ActOn[ciear] is not recommended, because 
there is a tendency to forget to unmark first. Use Selection.Clear instead. 

Match: PROCEDURE [pointer: ManagerOata] returns [match: boolean]; 

This procedure returns true if the caller is the current selection manager, which is 
assumed to be the case if and only if pointer is equal to the ManagerOata associated with 
the current selection (as specified by Set, SaveAndSet, or Restore). Note: A selection 
manager may opt to have nil as the ManagerOata. In this case, the manager should not 
use Match because it would not be able to distinguish itself from other managers using nil. 
However, Match[NiL] always returns false if there is no selection (that is, after 
Selection.Clear). 

UniqueTarget: procedure returns [Target]; 

• The UniqueTarget procedure allows a client to define its own private conversion type. It 
returns a new Target in [firstFree.Jast]. May raise Error [tooManyTargets]. The use of 
private target types severely limits the exchange of information between applications and 
should be avoided if possible. 

UniqueAction: procedure returns [Action]; 
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The UniqueAction procedure allows an application to define its own private operations on 
the selection. It returns a new Action in [firstFree.Jast]. May raise Error 
[tooManyActions]. 



40.2.3 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type ■ { 
tooManyActions, tooManyTargets, invalidOperation, 
operationFailed, didntAbort, didntClear}; 

tooManyActions May be raised by UniqueAction. 

tooManyTargets May be raised by UniqueTarget. 

invaiidOperation Raised if Copy or Move is called with a Value that does not 
implement the operation. 



operationFailed May be raised by a ValueCopyMoveProc if the operation is 
permitted but nevertheless fails, for example due to an NSFlie 
error. 



didntAbort, didntClear are never raised. 
40.3 Usage/Examples 



40.3.1 What Selection Is NOT 



The trash bin and insertion features of the Mesa interface are not supported. If they are 
needed, a separate (smaller) interface should be created for them, as they do not really 
require the generality available for actual selections. 

The Selection interface could, in theory, be extended to keep track of objects other than the 
current selection. A parameter could be added to Set, Convert, Enumerate,and so forth, 
that would describe the data object to be manipulated; the default would be the 
highlighted selection. Thus general information handles could be passed among modules, 
allowing one module to access another's data in whatever target format is most 
convenient. If there is sufficient demand for such a facility, it may be added someday. (It 
would probably call for a more suitable name than "Selection". Perhaps "OpaqueData"?) 



40.3.2 Random Details 



Requestors need to understand one slightly tricky concept: if they want the selection as a 
string and are prepared to handle very large strings, they should also be prepared to get 
the selection as an enumeration of strings if the selection is longer than 
Selection.maxStringLength. (The XDE Selection.Source mechanism has been eliminated.) 
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40.3.3 Examples of Storage Allocation for Manager's ConvertProc 

Here the various storage allocation cases are discussed that arise, depending on Target, 
how the selection is maintained by the manager,and so forth. 

• Simplest case: no storage associated with this Target, no copy/move. 

• Example: selection is a string in a window and Target « window. 

• Manager's ConvertProc should have: 

RETURN [ [value: window, ops: Seiection.nopFreeVaiueProcs] ] 

There is nothing allocated, nothing to free, so ops.f ree is Selection.NopFree. It makes no 
sense to copy or move a window this way, so ops.copyMove is nil. 

• Slightly more complex case: no storage associated with this Target, allow copy/move. 

• Example: selection is a piece of a larger backing string and is maintained as an 
xstring.ReaderBody aiid Target ■ string. 

• Manager's global frame: 

myValueProcs: Seiection.VaiueProcs [ 

free: Selection.NopFree, copy Move: CopyMoveString ]; 
SelectionOata: TYPE > record [ substring: xstring.ReaderBody,... ]; 

— substring points at the same bytes as the backing string 

• Manager's ConvertProc: 

OPEN seiectionOata: narrow [data, long pointer to SeiectionOata]; 
RETURN [ [value: @selectionOata.substring, ops: @myVaiueProcs] ]; 

— Selection wiH put zone into the context field. 

Here the requestor points directly at the SelectionOata.substring. The value. value | 
cannot be changed by the requestor until after the CopyMoveString is called. 

• Manager's CopyMoveString: 

V. value 4- xstring.CopyReader [r: narrow [v. value, xstring.Reader], 

z: narrow [v. context, uncounted zone] ]; 
v.ops.free4-NiL; 

After doing the copy, v.ops.free is replaced with nil, which causes Free to call FreeStd, 
which frees the copied ReaderBody and bytes. Note: CopyReader allocates both the 
ReaderBody and the bytes from a single allocation unit. 

Note: The storage for the SeiectionOata is allocated when he Selection.Set is done and 
deallocated when ActOn [clear] is called. 

• Typical case: some storage associated with this Target; allow copy/move 
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• Example: selection is a piece of a larger backing string and is maintained as an 
Environment.Biock and Target « string. 

• Manager's global frame: 

myValueProcs: Selection. ValueProcs *- [ free: nil, copyMove: CopyMoveString ]; 
SeiectionOata: type ■ record ( block: Environment.BtockM.. ]; 

- block represents the selection. 

" block.pointer points to the bacicing string. 

• Manager's ConvertProc: 

OPEN seiectionOata: narrow [data, long pointer to SeiectionOata]; 

RETURN [ [ 

value: zone.NEW [xstring.ReaderBody 

xstring.FromBlock [selectionOata.block], 
ops: ©myValueProcs] ]; 
— Selection puts zone into the context field. 
-ops.free ■ wimeansthatfreeStd will be called. 

Here a ReaderBody that points directly into our backing string is allocated. Free calls 
FreeStd, which frees the ReaderBody. 

• Manager's CopyMoveString: 

OPEN zone: narrow [v.context. uncounted zone] ; 
OPEN selectionSubstring: narrow [v. value, xstring. Reader] ; 
v.value xstring.CopyReader [ selectionSubstring, zone ]; 
zone.FREE [ ©selectionSubstring ]; - Frees the ReaderBody 

CopyReader copies both the ReaderBody and the bytes. After doing the copy, we free the 
ReaderBody. Note: After the copy, Free still calls FreeStd, which frees the copied 
ReaderBody and bytes. 

40.3.4 Detailed Flowchart of a Seiection.Convert 

Following is the exact sequence of events that takes place in performing a 
Seiection.Convert, showing what the requestor does, what the manager does, and what 
Selection does. Various storage allocation cases arise, depending on the Target, what the 
requestor wants to do,and so forth. Most of the cases are covered here. This is most useful to 
managers, but anyone desiring an overall understanding of Selection can benefit from 
following these details. 

• Requestor calls Seiection.Convert. 

• Convert calls the manager's ConvertProc. If the requestor provided a nil zone. Convert 
passes Heap.systemZone. 



Manager constructs a Value, potentially allocating storage for value. value f and/or 
for value.context f . value.ops may or may not be provided, depending on the selection 
Target and the manager. Manager returns value to Convert. 
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• If value.context is defaulted, Convert puts zone into value.context and returns to 
requestor. 



• If requestor just wants to look at the converted value (not copy or move it): 

• Requestor looks at value. value t • 

• Requestor calls Setoction.Free [©value]; 

• If value.ops is nil or value.ops.f ree is nil: 

• Free cal Is FreeStd . 

• FreeStd recovers the zone from value.context, does a zone. free 
[@value. value], and replaces value.ops with [free: NopFree, copyMove: nil]. 

• If value.ops.f ree is not nil: 

• Free calls value.ops.f ree [@value] (that is, the manager's VaiueFreeProc). 

• The manager's VaiueFreeProc recovers the zone from value.context (possibly 
a Held in a record pointed to by value.context) and releases any resources that 
were allocated in the ConvertProc. This includes not only the obvious freeing 
of storage from the zone (zone.FREE [@value.value] and/or Seiection.FreeContext 
[<§)value, zone]), but also, for example, closing or deleting any files that were 
created. 

• END. 

• If the requestor wants to move or copy the selection: 

e Requestor calls Selection. Move, Selection. Copy, or Selection. CopyMove, perhaps 
passing in data: long pointer , which points to a destination for the move/copy. 

• If value.ops is nil or value. ops. copyMove is nil, CopyMove raises Error 
[InvaiidOperation]. Otherwise, CopyMove calls value.ops.copyMove [@ya\ue, 
{copy, move}, data] (that is, the manager's ValueCopyMoveProc). 

• The manager's ValueCopyMoveProc recovers the zone from value.context, gets 
the destination of the move/copy from data (if appropriate), does the move or copy, 
calls Seiection.FreeContext [@value, zone] if necessary, does a zone.FREE 
[(SloldVaiue. value] if necessary. Note: This is freeing the original value. value, not 
the copied one. Now the manager can either leave value.ops.free as is or replace 
value.ops.free with Selection. FreeStd (if the newly copied value was allocated from 
zone and zone is in value.context), or replace value.ops.free with 
Selection. NopFree ( if there is nothing left to free). 

• CopyMove replaces value.ops.copyMove with nil to prevent another copy or 
move. 

• Requestor may retain the copied value indefinitely and/or call Selection.Free to free 
the copied value after using it (see above). 
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• END 



40.3.5 Sample ConvertProc and Requestor 

In this example of a simple selection manager, the selection is represented internally as a 
pair of indices within a single Mesa string. The string is inside a window. The indices 
designate the first character selected and the position beyond the last character selected. 
It is assumed that there are several windows of this type, and that each contains a single 
string within which selections may be made. It is also assumed that the manager's module 
contains a procedure TextForWindow that obtains the string associated with a window 
and various other obvious utilities and signals. The procedure Select makes a new 
selection. 



A ConvertProc is shown that implements the common targets. Observe the extremely 
heavy use of the defaults for the ops and context fields in the Value records. Because the 
Selection interface detects these defaults and applies the most common interpretations for 
Copy, Move, and Free, both the requestor and the manager are spared much of the coding 
effort. 



- Use dynamic storage for data; global variables make savelrestore awkward 
myZone: UNCOUNTED ZONE « ... ; 
SeiectionOata: TYPE ■ RECORD [ 

w: window.Handle, window containing this selection 

left, right: cardinal, 

marked: BOOLEAN <- false]; 

ValueContext: type » record [ - for use in Value.context fields 
zone: uncounted zone, 
w: window.Handle]; 



Select: procedure [w: window.Handle, left, right: cardinal] « { 
text: long string ■ TextForWindow[w]; 

IF text ■ nil OR left > text.length or right not in [teft..text.length] then 

error BogusSelection; 
S«lection.Set[ 

myZone.NEw[SelectionOata <- [w, left, right]], 

ConvertSelection, ActOnSelection]}; 

ConvertSelection: Seiection.ConvertProc ■ { 

<<[data: ManagerData, target: Target, zone: uncounted zone, info: Conversionlnfo] 

RETURNS [value: Value] > > 
OPEN selectlonData: narrow [data, long pointer to SelectionOata]; 
WITH i:info select from 
query « > 

for c: cardinal in [O..LENGTH(i.query]) do 
i.query[c].dlfflcuity <- 

if -^i.querytcj.enumeration then select i.query[c].target from 
window, string, length, position ■ > easy, 
integer a > moderate, 
ENDCASE ■ > impossible 
else -enumeratec/- if i.query[c].target ■ string then moderate 
ELSE impossible; 
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ENOLOOP; 

convert ■ > 

SELECT target FROM 

window a > return[[ seiectionData.w, Ssiection.nopFreeVaiueProcs]]; 
length ■ > RETURN[[zone.NEw[LONG cardinal <- 

selectionData.right • seiectionOata.left]]]; 
position ■ > RETURN[[zone.NEw(LONG CARDINAL «~selectionOataJeft]]]; 
string, integer « > 

IF seiectionOata.right • seiectionOata.left > Seiection.maxStringLength then 

RETURN[Selection.nullValue] 
ELSE { 

bik: Environment.Block « [LOOPHOLE[@TextForWindow[rec.w].text], 

seiectionOata.left, selectionOata.right]; 
r: xstring.ReaderBody xstring.FromBlock[blk]; 
IF target « integer then { 
bad: boolean «- false; 
num: long integer; 
num <— xstring.StringToNumber[@r 

! xstring.lnvalidNumber, xstring.Overflow » > 
{bad true; continue}]; 
return(if bad then seiection.nullValue else 
[zone.NEwfLONG INTEGER «- numl]]}; 
— target = string 
return[[ 

value: zone.NEw[xstring.ReaderBody <- r], 
ops: ©stringOps, 

context: zone.NEw[ValueContext <— [zone, selectionOata.w]] ]]}; 

enocase; 

enumeration ■ > if target =• string then { 

bIk: Environment.Block «- [LOOPHOLE[@TextForWindow[seiectionOata.w].text], 

selectionOata.leiPt, trash]; 
while block.startlndex < selectionOata.right oo 
block.stoplndexPlusOne *- 

MiN(block.startlndex * Seiection.maxStringLength, selectionOata.right]; 
IF i.proc[[ 

value: zone.NEw(xstring.ReaderBody <- xstring.FromBlock[blk]], 
ops: @stringOps, 

context: zone.NEw[ValueContext [zone, selectionOata.w]] ] 

].StOp THEN exit; 

block.startlndex *~ block.stopindexPlusOne; 

ENDLOOP}; 

endcase; 

RETURN[Seiection.nullValue]}; 

stringOps: Selection. ValueProcs *^ [FreeString, Copy String]; 

FreeString: Selection. ValueFreeProc — /i^: (/a/ueHanc//e7— « { 
context: long pointer to ValueContext ■ v.context; 

context.zone.FREE[@v.value]; - free the ReaderBody, but not the text bytes 
Seiection.FreeContext[ v, context.zone]}; 
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CopyString: Selection. ValueCopyMoveProc ■ { 

<<[v: VatueHandte, op: CopyOrMove, data: long pointer] >> 
context: long pointer to ValueContext ■ v.context; 
old: xstring-Reader • v. value; 

IF op ■ move THEN ERROR seiection.Error[invalidOperation]; 
v.value xstring.CopyReader[old, context.zone]; 
context.zone.FREE[@old]; 
Seiection.FreeContext[ v, context.zone]; 
v.ops.free#-NiL}; 

ActOnSelection: Seie€tion.ActOnProc • { 

<<[data: ManagerData, action: Action] returns [cieared: boolean false] > > 
OPEN selectionOata: narrow [data, long pointer to SelectionOata]; 

SELECT action FROM 

mark, unmark « > if selectionOata. marked # (action ■ mark) then 

InvertHighiightingfrec]; 
save, restore > > null; no special action need be taicen 
delete ■ > null; - deletion is not allowed via this interface 
ciearif Haslnsert « > null; - assume that this tool never has the insertion point 
clear ■ > {myZone.FREE[@data]; cieared true}; 
endcase}; 



Here are three sample requestors that might invoke the above manager code. The first 
requestor wishes to interpret the selection, if possible, as a string of digits and obtain the 
corresponding integer value. The second wishes to open a file whose name is the current 
selection. (Assume the existence of an NSFile routine that deals with XStrlng-format file 
names.) The third wishes to copy the current selection tq a Stream unless the selection 
comprises more than lOOOO characters. Since copying an NSFile to an arbitrary Stream is 
awkward at best, it does not use Convert(filel, but rather attempts to get the selection as 
one or more strings to send to the Stream. 

- Example 1: obtain selection as an integer and do something with it 
num: long integer; 

ok: boolean; 

[ok, num] 4-Seie€tion.ConvertNumber[integer] ; 

IF ok THEN { 

< < do whatever it was we wanted to do with num >>} 

ELSE { 

< < report error, or ignore it> > }; 

- Example 2: use current selection as name of file to open 
v: Selection. Va t ue <-Selection.Convert[string]; 

file: NSFiie.Handle NSFiie.nullHandle; 

// v.value is nil it means there's no selection, or it can't be converted to a string, 
» or the string would be so long it's not a reasonable name anyway 

IF V.value # NIL THEN { 

file 4- NSFiie.OpenByName[v. value ! NSFUe.Error a > continue]; 
Selection.Free[@v]}; 

- Example 3: copy selection to a Stream (handle is in sH) unless length > 10000 
bytes: long cardinal; ok: boolean; 

v: Selection. Value; 
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[ok, bytes] <^Seiection.ConvertNumber[iength] ; 
IF ok AND bytes < ■ 10000 then { 

V 4- S«lection.Convert[string]; 

IF V. value # NIL THEN PutReader[v, sH] 

ELSE [] *~ Seie<tion.Enumerate(PutReader, string, sH]}; 

PutReader: s«i«ction.EnumerationProc * { 

< < [element: Value, data: RequestorData] returns [stop: boolean *- false] > > 

sH: stream.Handie ■ data; 

sH.PutBtock[xstring.Block[element.value].biock 

! stream.TimeOut, Volume.! nsufficientSpace » > {stop <- true; continue}]; 
seiection.Free{@element] }; 

40.3.6 Sampie Use of Enumeration 

In this example of the use of the enumeration facility, the user has asked to copy or MOVE 
the selection to the desktop. The desktop does not particularly care what the selection is: it 
simply requires that it be rendered as one or more files. If the operation is a MOVE, it is 
better not to do it as a copy-then-delete; instead, obtain the existing files and relocate 
them. 

op: Seiection.CopyOrMove ... ; -« Setting is determined by the TIP table interpreter 
iFSeiection.Enumerate[CopyMoveFiieToDesktop, file, @op].aborted then { » error - }; 



CopyMoveFileToOesktop: Seiection.EnumerationProc a { 
op: LONG POINTER TO Seiection.CopyOrMove ■ data; 

file: LONG POINTER TO NSFiie.Reference <~ element. value: - This is readonly until Copied 
or Moved 

Seiection.CopyMove[@element, op f , handleForOesktop 
! Selection.Error ■ > SELECT COde FROM 

- Owner will not let us have it for some reason 
invalidOperation, operationFailed « > {stop true; continue}; 

ENDCASE « > reject]; 

IF stop then {seiection.Free[@eiement]; return}; 

file 4— element. value; - The value was probably changed by CopylMove 
file is now a Reference to a file that is of no interest to the selection manager 

< < Create any associated structures necessary for keeping track of the icon > > 

< < Might also need to set position attributes, etc.; it would be more efficient 
to set the attributes as part of the Copy or Move, but this would probably 
require an awkward structuring ofCopyMove's data parameter > > 

Seiection.Freet@element]; - free the storage associated with the Reference 

}; 

Here are two cases in which the above code might be invoked. First, assume the selection 
is a set of documents in an open folder. The folder's conversion proc calls 
CopyMoveFileToOesktop once for each document, with element being the 
NSFile.References for the already existing files. The ops.copyMove provided by the folder 
implementation either does an NSFile.Copy or an NSFile.Move to transfer the file to the 
desktop directory; it updates element.value if necessary to refer to the new file. If the 
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operation is a move, copyMove also reflects the deletion in the folder's window. It might 
also update the selection data if, for instance, the seiection is represented internally as a 
range of positional indices within the directory. 

If the selection is a set of printers in the Star directory icon, no files exist for them until 
they are copied to the desktop. For each printer, the conversion procedure creates a file 
from scratch and passes it to CopyMoveFileToDesktop. This time, however, 
ops.copyMove calls NSFrLE.Move regardless of the operation requested, because it is not 
possible to remove objects from the Star directory. (Alternatively, it could call NSFiie.Move 
to do a copy and raise Error[invalidOperation] if asked to do a move.) Meanwhile, the 
ops.free originally included with each element is Selection. NopFree; if the user chooses not 
to do anything with the printer, the Star directory enumeration code simply changes the 
attributes of the file to refer to the ne.xt printer in the enumeration and uses the same file 
again. Thus ops.copyMove must also set a flag indicating that a new dummy file must be 
created if there are any more elements in the enumeration. 

The important thing to note is that, in the first example, doing a copy involved creating a 
new file, whereas in the second example it didn't. (Instead, it needed to ensure that the file 
not be re-used when the enumeration continued.) The requestor had no way to decide 
whether the object needed to be copied. The decision was left up to the selection manager 
by means of the ops procedure. 
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40.4 Index of Interface Items 

Letters in parentheses indicate a description for a 



requestor (R) or a manager (M). 

Item . Page 

Action: type 17 

ActOn: procedure 19 

ActOnProc: TYPE 13,17 

Can YouCon vert: procedure 9 

Clear: procedure 19 

ClearOnMatch: procedure 19 

Conversionlnfo: TYPE 12,13,14 

Convert: procedure 5 

ConvertNumber: procedure 8 

ConvertProc: TYPE 12 

Copy: procedure 1 1 

CopyMove: ValueCopyMoveProc 11 

CopyOrMove: type 1 1 (R), 1 6(M) 

Difficulty: type 9 

Discard: procedure 19 

Enumerate: procedure 10 

EnumerationProc: type 10 

Error: error 20 

ErrorCode: type 20 

Free: procedure 8 

FreeContext: PROCEDURE 17 

FreeStd: ValueFreeProc 15 

HowHard: procedure 9 

ManagerData: TYPE 12 



Item Page 

Match: procedure 19 

maxStringLength: cardinal 1 1(R), 14(M) 

Move: PROCEDURE 11 

NopFree: ValueFreeProc 16 
nopFreeValueProcs: long pointer to ValueProcs 16 

nullValue: Value 5 

Query: procedure 9 

QueryElement: TYPE 9(R), 13(M) 

Reconversion: SIGNAL 10 
ReconvertDuringEnumerate:PROCEDURElO 

RequestorData: TYPE 10 

Restore: PROCEDURE 18 

SaveAndSet: procedure 18 

Saved: TYPE 18 

Set: PROCEDURE 12 

Target: type 6 

UniqueAction: procedure 20 

UniqueTarget: procedure 20 

Value: TYPE 5(R),13(M) 
14(M) 

ValueCopyMoveProc: type 11(R), 16(M) 

ValueFreeProc: TYPE 15 

ValueHandle: TYPE 8(R), 14(M) 

ValueProcs: TYPE 15 
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41.1 Overview 

The SimpleTextDisplay interface provides facilities for displaying, measuring, and 
resolving strings of Xerox Character Code Standard text. SimpleTextDisplay deals with 
text in a single font— normally the standard system font--and does not support boldface, 
italic, sub- and superscript, and other text properties. SimpleTextDisplay does not 
implement editable or selectable text, but it provides the building blocks that can be used 
to implement such things (See SimpIeTextEdit.) 

Most clients will bo interested mainly in the procedure StringlntoWindow, which simply 
displays one or more lines of text at a given location in a window. 

More sophisticated clients may want to use StrlnglntoBuffer, which formats text into a 
special bitmap buffer rather than painting it into a window: MeasureString, which 
determines how wide a string would appear if painted into a window without actually 
painting it; or FillResolveBuffer, which computes the position of each character of an 
already displayed line of text. 

All width values taken or returned by SimpleTextDisplay procedures are in terms of 
screen pixels (bits). 

41.2 Interface Items 

41.2.1 Simplest Way to Display Text 

StringlntoWindow: procedure [ 
string: xstring.Reader, 
window: window. Handle, 
place: window.Place, 
lineWidth: cardinal «~cardinal.last, 
maxNumberOf Lines: cardinal 

lineToLineDeltaY: cardinal 4-0, «> default: systemFontHeight 

wordBreak: boolean «- true, 

flags: BitBit.BitBltFlags <- Display. paintFlags] 

RETURNS [lines, lastLineWidth: cardinal]; 
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Displays string in window, starting at place, place refers to the upper-left corner of the 
first character. Each line is no more than llneWidth pixels wide, and there will be no more 
than maxN urn berOf Lines lines. If wordBreak is true, StringlntoWindow tries to break 
lines between, rather than within, words. The flags determine what BitBit function is used 
to place the new bits in the window; the default is to OR them into the window's e.xisting 
bitmap. When a new line is started, its y-position is lineToLineOeltaY below the y-position 
of the previous line; if llneToLlneOeltaY is defaulted to 0, each line is systemFontHeight 
pixels below the previous one. lines is the number of lines that were actually painted. 
lastLlneWldth is the width of the last line displayed. If the string ends with a carriage 
return and maxNumberOf Lines are not exceeded, then lastLineWidth is 0 and lines 
include an empty line following that carriage return If the string is empty, 
StringlntoWindow returns [lines: 0, lastLineWidth: 0]. 

StringlntoWindow always uses the standard .system font, a Flushness of fromFirstChar, 
and a StreakSuccession of fromFirstChar. (See §41.2.4 for an explanation of Flushness and 
StreakSuccession.) 

systemFontHeight: readonly cardinal; 

systemFontHeight is the height (in pixels) of the system font. 

41.2.2 StringlntoBuffer 

StringlntoBuffer: procedure [ 
string: xstring.Reader, 
bufferProc: BufferProc, 
iineWidth: cardinal 4-cardinallast, 
wordBreak: boolean true, 

StreakSuccession: StreakSuccession <- fromFirstChar, 
font: SimpieTextFont.MappedFontHandie «-nil] 

RETURNS [lastLineWidth: cardinal, result: Result, rest: xstrmg.ReaderBody]; 

Formats string into a bitmap buffer using font and calls bufferProc for each line. (See 
BufferProc below for a description of the parameters passed to bufferProc.) If font is nil, 
the system font is used. StringlntoBuffer stops reading characters in the string and calls 
bufferProc when one of the following events occurs: 

• A character whose TextBit flags are [stop: true, pad: false] is encountered, such as a 
carriage return. bufferProc is called with a result of stop. The string passed to 
bufferProc ends with the carriage return. 

• The IineWidth (measured in pixels) would be exceeded by formatting the next 
character. bufferProc is called with a result of margin. The string passed to bufferProc 
ends with the last character that did fit (if wordBreak is false) or with the last 
character before the beginning of the word that did not fit (if wordBreak is true). 

• There are no more characters to be read. bufferProc is called with a result of normal. 
The string passed to bufferProc ends with the last character of the string passed to 
StringlntoBuffer. 

Result: TYPE « {normal, margin, stop}: 
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If result ■ normal, or bufferProc returns continue « false, StringintoBuffer returns the 
following values: result ■ the result last passed to bufferProc, rest « a substring 
containing characters not yet processed (restoffset will be the string.iimit last passed to 
bufferProc), lastLineWidth ■ the dims.w last passed to bufferProc. 

If result is not normal, and bufferProc returns continue ■ true, StringintoBuffer 
continues processing the remainder of string and calls bufferProc again. 

If string is empty, StringintoBuffer returns [width: 0, result: normal, rest: 
xstring.nullReaderBody] and does not call bufferProc at all. 

BufferProc: type » procedure [ 
result: Result, 
string: xstring. Reader, 
address: Environment.BitAddress, 
dims: window.Oims, 
bitsPerLine: cardinal] 
RETURNS [continue: boolean]; 

A BufferProc is called once on each line of text processed by StringintoBuffer. The 
procedure should return true if it wants StringintoBuffer to process the remaining text 
(and.to call the BufferProc again). The parameters should be interpreted as follows: 

result explains why StringintoBuffer decided to end the current line of text: 

stop if the line ends with a carriage return character. 

normal if there are no more characters to be processed after this line. In this case, 
StringintoBuffer ignores the continue boolean that the BufferProc 
returns. 

margin if the line was broken to avoid exceeding the lineWidth passed to 
StringintoBuffer. 

string is a substring of the string passed to StringintoBuffer, which contains exactly those 
characters on this line. If the line ends with a carriage return, the carriage return is the 
last character in string. 

address is the address of the bitmap buffer into which the current line's characters have 
been formatted. 

dims is the dimensions of the formatted part of the bitmap buffer, dims.h is always equal 
to the height of font passed to StringintoBuffer (or to systemFontHelght if font was nil). 
dims.w is always < = the lineWidth passed to StringintoBuffer. 

bitsPerLine is the number of bits per bitmap line in the buffer (that is, how many bits to 
add to address to reach the beginning of the next bitmap line). It is always a multiple of 
16. 

Fine point: If the string passed to StringintoBuffer 'ends in a carriage return, and the BufferProc returns TRUE, 
the BufferProc is called one last time with an empty string (offset and limit both equal to the passed string.iimit). 
an empty bitmap <dims.w at 0), and result s normaL 
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41.2.3 Measure and Resolve 



GetCharWidth: procedure [char: xchar.Character, 
font: simpieTextFont.MappedFontHandle 4-nil] . 
RETURNS [width: cardinal]; 

Returns the width of the specified character in the specified font. If font is nil, the 
system font is used. 

MeasureString: procedure [ 
string: xstring.Reader, 
lineWidth: cardinal <>cardinal.last, 
wordBreak: boolean <- true, 

streakSuccession: StreakSuccession 4-fromFirstChar, 

font: siiiipieTextFont.MappedFontHandie *-n\l] 

returns [width: cardinal, result: Result, rest: xstrmg.ReaderBody]; 

MeasureString determines the numher of horizontal pixels that displaying string in the 
specified font would take up. If font is nil, the system font is used. If wordBreak is true and 
the string will not fit into lineWidth pixels, MeasureString attempts to end the line 
between words, result is one of the following: 

stop If a carriage return character is encountered in the string before lineWidth 
pixels have been measured. In this case, width is the pixel width of those 
characters up to and including the carriage return, and rest begins with the 
first character following the carriage return. 

margin If the string will not fit within lineWidth horizontal pixels. In this case, width is 
the pixel width of those characters that do fit (possibly backed up to the end of 
the last word that entirely fits on the line, if wordBreak is true), and rest begins 
with the first character that does not fit. 

normal If the string contains no carriage returns and fits entirely within lineWidth 
horizontal pixels. In this case, rest is empty. 

If string is empty, MeasureString returns (width: 0, result: normal, rest: 
xstring.nullReaderBody]. 



FiilResolveBuffer: procedure [ 
string: xstring.Reader, 
lineWidth: cardinal 4-caroinal.last, 
wordBreak: boolean true, 

StreakSuccession: StreakSuccession 4>fromFirstChar, 

resolve: ResovleBuffer, 

font: simpieTextFont.MappedFontHandle «-nil] 

RETURNS [width: CARDINAL, result: Result, rest: xstnng.ReaderBody]; 

FiilResolveBuffer measures the x-offset of the left edge of each character of string relative 
to the left edge of the leftmost character and stores the measurements in the resolve array. 
The measurements are in units of pixels. The offset of the leftmost character is zero. There 
is one element in the resolve array for each of the bytes (not characters) of string. The 
measurement stored for each byte of string is the measure for the character that the byte is 
a part of. The measure stored for character set shift codes is that of the next actual 
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character in the string. (For the meaning of the return values, see the description of 
MeasureString.) 

The resolve buffer must be string.limit'String.offset •»• 1 words long to avoid smashing 
memory. 

If string.context.suffixSize ■ 1 and the string contains no character set shifts (377Bs) (thut 
is,if there is one byte per character), then: 

resoive[0] is assigned x-offset of the character string.bytes{string.offset], 
resoive[1] is assigned the x-offset of the character string.bytes[string.offset •»• 1], 

• " • • » 

resolvetstring. limit-string. off set-1] is assigned the x-offset of the character 
string.bytes(string.limit^1]. 

If the string does contain 377Bs, then any character set shift bytes ([377B, chsetj or f377B, 
377B, 0]) are assigned the same resolve value as the following character code byte. 

In any part of the string that is in Stringietl6 format (2 bytes per character), both bytes of 
each character are assigned the same resolve value. 

If a sequence of characters would be displayed as a ligature~a single graphic representing 
several adjacent characters-then all of those characters are assigned the same resolve 
value. 

In all cases, resolve[string.limit-string.offset] is assigned the pixel width of the string- 
the same value that is given to the returned value width. 

If string is empty, FillResplveBuffer returns [width: 0, result: normal, rest: 
xstring.nutlReaderBody] and does not write into the resolve buffer at all. 

ResoiveBuffer: TYPE « long descriptor for array [0..0) of cardinal; 

NewResolveBuffer: procedure [words: cardinal] returns [ResoiveBuffer]; 

Allocates a resolve buffer of the specified length for later use by FillResolveBuffer. Non- 
SimpieTextOisplay clients of TextBIt are also encouraged to obtain their resolve buffers by 
calling this procedure, because SimpieTextDlsplay caches resolve buffers for efficiency. 

FreeResolveBuffer: procedure [ResoiveBuffer]; 

Frees a resolve buffer allocated by NewResolveBuffer. 

41.2.4 Multinational Items 

Flushness: TYPE « {flushLeft,flushRight,fromFirstChar}; 

A Flushness determines where to display a line of text that does not fill the entire bitmap 
width allotted to it. flushLeft places the leftmost character at the left edge of the bitmap. 
flushRight places the rightmost character at the right edge of the bitmap. fromFirstChar is 
equivalent to flushLeft if the first character of the text has xcharJoinOirection a 
nextCharToRight (for example, Latin and most other alphabets); it is equivalent to 
flushRight if the first character of the text has JoinOirection ■ nextCharToLeft (for 
example, Arabic and Hebrew letters). 
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PeekForFlushness: procedure [requestedFlushness: Flushness, string: xstring.Reader] 
RETURNS [Fiushness]; 

Returns a real fiushness (either fiushLeft or flushRight, not fromFirstChar) appropriate for 
the passed requestedFlushness and string. 

StreaicSuccession: type ■ {leftToRight^rightToLeft, fromFirstChar}; 

PeekForStrealcSuccession: procedure [ 

requestedStrealcSuccession: StreaicSuccession, string: xstrin9.Reader] 
RETURNS [StreakSuccession]; 

Returns a real streak succession (either leftToRight or rightToLeft, not fromFirstChar) 
appropriate for the passed requestedStreakSuccession and string. 

41.3 Usage/Examples 

The only non- Xerox Character Code that is significant to SimpleTextDisplay Is Carriage 
Return. No other control characters are recognized. 

All width values taken or returned by SimpleTextDisplay procedures are in terms of 
screen pixels (bits). If the client passes its own font to SimpleTextDisplay, its mica widths 
should be equal to its pixel widths. Fonts passed to SimpleTextDisplay should have no 
measurements actually in micas. 

41.3.1 StiinglntoWindow 

rb: xstring.ReaderBody 4-xstring.FromSTRING ("This is an example."L]; 

[] 4-SimpieTextDisplay.StringlntoWindOW [ 
string: @rb, 
window: window, 
place: [10,10]]; 

41.3.2 StringlntoBuffer 

This example shows an implementation of String! ntoWindow using StringlntoBuffer. 

MyStringlntoWindow: procedure [ 
string: xstring.Reader, 
window: window.Handle, 
place: window.Place, 
lineWidth: cardinal 4-caroinal.last, 
maxNumberOf Lines: CARDINAL 4-1, 
lineToLineDeltaY: cardinal 4-0, 
wordBreak: boolean <- true, 
flags: BitBit.BitBitFlags 4-Dispiay.paintFlags] 
RETURNS [lines: cardinal, lastLineWidth: cardinal] ■ { 

MyBufferProc: SimpleTextDisplay. Buff erProc =« { 

Display. Bitmap [window, [place, dims], address, bitsPerLine, flags]; 
lines 4- lines * 1; 
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place.y 4- piace.y + lineToLineOeltaY; 

RETURN [continue: lines < maxNumberOf Lines]; 

}; 

IF lineToLineOeitaY a 0 then lineToLineOeitaY 4-sifnpieTextOispiay.systemFontHeight; 
lines «->0; 

[lastLineWidth: lastLine Width] 4-simpieTextoispiay.StringlntoBuffer [ 
string: @rb, 

bufferProc: MyBufferProc, 
lineWidth: lineWidth, 
wordBreak: wordBreak]; 

>; 



41 7 



41 



SimpleTextDisplay 



41.4 Index of Interface Items 



Item 
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BufferProc: type 
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GetCharWidth: procedure 
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FiilResolveBuffer: procedure 
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Flushness: type 
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FreeResoiveBuffer: procedure 
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MeasureString: procedure 
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NewResolveBuffer: procedure 
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PeekForFlushness: procedure 
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PeekForStreakSuccession: procedure 
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Result: type 
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ResolveBuffer: type 
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StreakSuccession: type 
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StringintoBuffer: procedure 
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Stringinto Window: procedure 
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systemFontHeight: readonly cardinal 
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42.1 Overview 

The SimpleTextEdit interface provides facilities for presenting short editable pieces of 
text, known as fields^ to the user. The user can select, move, copy, delete, and edit the text. 
Such text can contain any sequence of characters supported by the Xerox Character Code 
Standard. 

All the text in a SimpleTextEdit field is displayed in a single font. SimpleTextEdit does not 
provide multiple fonts, boldface, italics, subscript, superscript, paragraph and character 
properties, and other elaborate editor features. 

SimpleTextEdit fields are most appropriate for short pieces of text, preferably less than 30 
lines long. They are not appropriate for editing entire files, for example. 

SimpleTextEdit is primarily intended to support text items in the higher-level 
FormWindow interface but is also provided as a public interface for those clients who may 
need it. Most clients will use FormWindow rather than SimpleTextEdit. FormWindow 
provides support for general forms, including choice, boolean, and command items. 
FormWindow also automatically adjusts the position of other fields when a text field 
becomes taller or shorter. The client of SimpleTextEdit must provide its own procedure for 
this. 

42.1.1 Creating Fields 

Fields are created by calling CreateField. Before creating any fields, however, a 
FleidContext must first be created by calling CreateFieldContext. There must be one 
FieldContext for each window that will contain Fields. The FleidContext returned by 
CreateFieldContext should be passed to CreateField for each field to be created. When a 
field is created, only the desired window.Oims of the field need to be supplied. 
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42.1.2 Displaying a Field 

A field is displayed by calling RepaintField. Before a field can be displayed, it must be 
given a window.Place by calling SetPlace. Failure to call SetPlace before displaying a field 
results in Error [fieldlsNoPlace]. 

42.1.3 Notifying a Field 

Notifications are passed to a field by calling TIPResults. SimpleTextEdit attaches neither a 
window displayProc nor a Tip.Notif yProc to a window. The client provides these procedures 
and then calls RepaintField for display and TIPResults for notifications. If there is more 
than one field in a window or a single field does not occupy an entire window, the client 
must resolve mouse buttons to determine which field should get the notification. 

42.2 Interface Items 

42.2.1 FieldContext 

FieidContext: type « long pointer to FieldContextObject; 
FieldContextObject: type; 

CreateFieldContext: procedure [z: uncounted zone, window: Window.Handle, 
changeSlzeProc: ChangeSizeProc, font: SimpieTextFont-MappedFontHandle «- nil] 
RETURNS [fc: FieldContext]; 

A FieldContext holds information that is common to all Fields in a given window. There 
must be exactly one FieldContext associated with any window containing Fields. The 
FieldContext contains such information as the fields' font, the current input focus, the 
field containing the current selection, and so forth. 

CreateFieldContext creates a FieldContext for window, which can be later used to create 
individual Fields (see CreateField). Only one FieldContext should be created for any 
window. All storage associated with the FieldContext and its Fields is allocated from z. 
The changeSizeProc is called whenever any field's height is changed (see ChangeSizeProc 
below). All text in the FieidContext's Aelds will be displayed with the supplied font. If font 
is defaulted (the usual case), the standard system font is used. 

DestroyFieldContext: PROCEDURE [fc: FieldContext]; 

DestroyFieldContext destroys a FieldContext. If any of fc's fields has the input focus, it 
clears the input focus and turns off the blinking caret. If any of fc's fields contains the 
current selection, it clears and dehighlights the selection. DestroyFieldContext does not 
destroy each field. The client should either call OestroyField on each field before calling 
DestroyFieldContext or else dispose of the associated uncounted zone after calling 
DestroyFieldContext. The client should not call DestroyField after calling 
DestroyFieldContext. 
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42.2.2 Creating Fields 

Field: TYPE ■ long pointer to FieidObject; 

FieidObject: type; 

CreateFieid: procedure [ 
clientOata: long pointer, 
context: FieidContext, 
dims: window.Oims, 
initString: xstring. Reader <>nil, 
flushness: simpieTextoispiay.Flushness 4-fromFirstChar, 
streaicSuccession: simpieTextoispiay.StrealcSuccession f romFirstChar, 
readonly, password : boolean <- false, 
fixedHeight: boolean^ false, 
font: simpi«T«xtFont.MappedFontHandle 4-nil, 
backing Writer: xstring.Writer«-NiL, 
SPECIALKey board: Biacl(Keys.Keyboard «-nil] 
RETURNS [f : Field]; 

A Field is an area within a window that contains editable text. It is the primary object 
manipulated by this interface. 

CreateFieid creates a field with appropriate attributes. The field uses the window, font, 
zone, and ChangeSizeProc of the passed FieidContext. 

ciientData is a pointer that is not interpreted but is returned by GetClientOata. Clients 
may use it to associate their own data with each individual field. 

dims are the initial dimensions of the field. As the field's contents change, its height may 
change as well (unless fixedHeight is true). However, the height never becomes smaller 
thandims.h. 

initString is the initial contents of the field, if any. CreateFieid copies the string; the caller 
continues to own it when CreateFieid returns. 

flushness controls where to place lines of text that do not fill the entire width of the field. If 
flushness ■ ftushLeft, the leftmost character is next to the field's left edge. If flushness ■ 
flushRight, the rightmost character is next to the field's right edge. If flushness ■ 
fromFirstChar, the field is flushLeft if its first character has xcharJoinDirection ■ 
nextCharToRight (for example, Latin and most other alphabets), and flushRight if the first 
character has JoinOirection ■ nextCharToLeft (for example, Arabic and Hebrew letters). 

StreaicSuccession indicates whether the text of the field flows leftToRight or rightToLeft. 
The default (fromFirstChar) causes the streaicSuccession of the field to be determined from 
the first character in the field. Latin and most other alphabets fiow leftToRight. Arabic 
and Hebrew fiow rightToLeft. 

If readonly is true, the user cannot change the field's contents. SetlnputFocus is a no-op on 
a readonly field, and any call on TlPResults that normally sets the input focus to this field, 
or change the field's contents does not do so. However, SetValue still works on a readonly 
field. 

If password is true, each character of the field is displayed as a If a selection is made 
within a password field, and that selection is moved or copied, * characters are moved or 
copied rather than characters from the field's actual backing string. s«l«ction.Convert also 
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produces a string of " characters. The only way to access a password field's actual content 
istocallGetVaiue. 

If fixedHeight is true, the field's height never changes regardless of the field's content. The 
context's ChangeSizeProc is never called with this field as an argument. 

font allows each field to be a different font If font is nil, then the system font is used. 
Note: This does not provide for general attributed text in SimpleTextEdit fields. The entire 
field is all the same font. 

If backing Writer is nil (the usual case), SimpleTextEdit allocates the field's backing string 
from the context's zone, expands it as needed, and deallocates it when the field is 
destroyed. If backingWriter is non-NiL, SimpleTextEdit uses it as the backing string and 
does not deallocate it when the field is destroyed. If backing Writeir.zone is nil, TiPResults 
raises Error [noRoomin Writer] whenever it tries to do an operation that would overflow 
the backing string. 

SPEGALKey board allows a client-specified interpretation of the central keypad. 
DestroyFleld: procedure [f : Field]; 

Destroys the passed field. If the field has the input focus, it clears the input focus and turns 
off the blinking caret. If the field contains the current selection, it clears and dehighlights 
the selection. DestroyFleld must not be called after the field's context has been destroyed. 

GetValue: procedure [f: Field] returns [xstnng.ReaderBody]; 

Returns the field's current contents. The returned string points directly into the field's 
backing storage; it is not copied. 

SetValue: procedure [f : Field, string: xstring.Reader, repaint: boolean 4- true]; 

Change the contents of the field. Copies the string, which the caller continues to own after 
SetValue returns. Repaints the field unless repaint is false. In that case, the caller should 
call RepaintField before returning to the notifler. If the field has the input focus, it clears 
the input focus and turns off the blinking caret. If the field has the selection, it clears and 
dehighlights the selection. If repaint is true, the field may become taller or shorter, 
triggering a call on the ChangeSizeProc. 



42.2.3 Displaying a Field 

RepaintField: procedure [f : Field]; 

Repaints the field. 

SetPlace: procedure [f : Field, place: window.Place]; 

Changes the window-relative location of the field. This procedure must have been called at 
least once before calling GetBox, RepaintField, or TiPResults; otherwise, calling those 
procedu]|[es raises Error [fieidisNoplace]. Does not repaint the field. SetPlace is intended for 
two primary uses: to set the initial location of a field and to change it from within a 
ChangeSizeProc when another field gets taller or shorter. 
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42.2.4 Notifying a Field 

TIPResults: procedure [f : Field, results: TiP.Results] 
RETURNS [tooklnputFocuSr changed: boolean]; 

Passes results to the specified field. The field is changed as appropriate. For example, if 
results contains a PointDown atom, the character closest to the cursor is highlighted. 
Details of the exact processing performed for each possible result are described below. If 
the field's contents are changed while processing the results, changed will be true. If the 
input focus was set to this field, tooklnputFocus will be true. Both booleans start out false 
but may become TRUE when strings or atoms are encountered in results. Any TiP.Results 
that change the field's contents also cause the field to be repainted; this may cause the 
field to become taller or shorter, triggering a call on its ChangeSizeProc. 

If a string is encountered in results, the string is inserted into the field at the current 
insertion point. This clears the selection if the current insertion point is at either end of 
the selection. The passed field must be the current input focus and not readonly; 
otherwise, the string is ignored. 

The following atoms in results cause actions to be taken. An * indicates that the passed 
field must be the current input focus; if not, the atom is Ignored. Unless otherwise 
indicated, tooklnputFocus and changed remains unaffected after this atom is processed. 

AdjustDown (should be preceded by a coords result): Extends or contracts the current 
selection, depending on coords earlier in results. If there is no current selection, creates 
one extending from the current insertion point to a place determined by coords. This is a 
no-op if the passed field is not the current input focus or selection. 

AdjustMotion (should be preceded by a coords result): Same effect as AdjustDown, 
although a diSierent algorithm is used to determine which endpoint of the selection is 
being moved. 

Backspace*: If the field is not readonly, deletes the character before the insertion point 
and sets changed to true. This clears the selection if the current insertion point is at either 
end of the selection. 

BackWord*: If the field is not readonly, deletes the word before the insertion point and 
sets changed to true. This clears the selection if the current insertion point is at either end 
of the selection. If the field is a password field, acts like a Backspace. 

CopyDown: Calls TiPStar.SetMode [copy]. 

CopyModeDown (should be preceded by a coords result): If the field is not readOniy, 
places the caret at an appropriate place in the field, depending upon coords earlier in 
results, but leaves the selection alone. tooklnputFocus will be true. If the field is 
readonly, tliis is a no-op and tooklnputFocus is unchanged. 

CopyModeMotion (should be preceded by a coords result): Same effect as 
CopyModeDown. 

CopyModeUp*: If the field is not readonly, inserts the current selection at the current 
insertion point, sets the selection to be the newly inserted text, and calls TiPStar.SetMode 
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[normai]. If the selection is not empty, repaints the field and sets changed to true. If the 
field is readonly, this is a no-op and changed remains unaffected. 

OeieteDown: Calls s«iection.ActOn [delete], changed becomes true. 

MoveOown: Calls TiPStar.SetMode [move]. 

MoveModeOown (should be preceded by a coords result): Same effect as 
CopyModeOown. 

MoveModeMotion (should be preceded by a coords result): Same effect as 
CopyModeOown. 

MoveModeUp*: Same effect as CopyModeUp, except that It does a Selection.ActOn [delete] 
on the current selection before setting the selection to be the newly inserted text. Note 
that if the current selection is in a readonly field, no deletion occurs, and it acts exactly 
like a CopyModeUp. 

NewLine*: If the field is not readonly, inserts an Asdi.CR at the current caret position. 
This clears the selection if the current insertion point is at either end of the selection, 
changed will be true. If the field is readonly, is a no-op and changed is unaffected. 

NewParagraph*: Same effect as NewLine. 

PointDown (should be preceded by a coords result and a time result): Sets the current 
selection to be in the passed field. The location of the selection depends upon coords earlier 
In results; the extent (character, word, paragraph) depends on its current extent and time 
earlier in results. tooklnputFocus is true unless the field is readonly. 

PointMotion (should be preceded by a coords result): Moves the current selection within 
the field. If the current selection is not in the field, it sets it there. The location of the 
selection depends upon coords earlier in results. The extent of the selection (character, 
word, paragraph) remains unchanged. tooklnputFocus is true unless the field is readonly. 

PointUp (should be preceded by a time result): Sets the last-click time, which determines 
whether a subsequent PointDown represents a multiple click. 

Stop: Calls TiPStar.SetMode [normai] . 

42.2.5 Miscellaneous Get and Set Procedures 

GetBox: procedure [f : Field] returns [box: window.Box]; 

Returns the box (dimensions and place) currently occupied by f. box. place is relative to 
the field's window and is always the last value passed to SetPiace. Raises Error 
[fleldlsNoplace] if SetPiace has never been called on this field. 

GetCiientData: procedure [f: Field] returns [clientData: long pointer]; 

Returns the clientData that was passed to CreateField. 

GetFieldContext: procedure [f : Field] returns [FieldContext]; 
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Returns the field context that was passed to CreateFieid. 

GetFlushness: procedure [f: Field] returns [SimpiaTextoispiay.Ftushness]; 

Returns the current Fiushness off. 

GetFont: procedure [f : Field] 
returns [simpi«TextFont.MappedFontHandle]; 

GetlnputFocus: procedure [fc: FleldContext] returns [Field]; 

If some field associated with fc has the input focus, it returns that field; otherwise, it 
returns nil. 

GetCaretPiace: procedure [context: FleldContext] 
returns [place: window.Place]; 

If £Uiy field in the FleldContext contains the current type-in point, this procedure returns 
the location of that point. If not, place = [- 1,-1]. This is useful for determining that the 
window must be scrolled to make the caret visible to the user. 

GetReadOnly: procedure [f : Field] returns [boolean]; 

Returns the current value of readOniy for f. 

GetStreakSuccession: procedure [f: Field] returns [simpieTextoispiay.StreakSuccessron]; 
Returns the current StreakSuccession of f . 

GetWindow: procedure [fc: FleldContext] returns [window: window.Handle]; 

Returns the window that was passed to CreateFieldContext. 

GetZone: procedure [fc: FieldContext] returns [uncounted zone]; 

Returns the uncounted zone that was passed to CreateFieldContext. 

SetDims: procedure [f : Field, dims: window.Dims]; 

SetDlms sets the dimensions for f . 

SetFixedHeight: procedure [f : simpiaT6xtEdit.Field, 
fIxedHelght: boolean]; 

Allows setting the fixed-height attribute for a field. 

SetFlushness: procedure [f : Field, new: simpieTextoispiay.Flushness] 

RETURNS [old: SimpieTextOispiay.FtushneSS]; 
Changes the field's fiushness and returns the old fiushness. Does not repaint the field. 
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SetFont: procedure [f : Field, 
font: SifnpieTaxtFont.MappedFontHandle 4-nil]; 

If font ■ NIL, the system font is used. 

SetlnputFocus: procedure [f: Field, beforeChar: cardinal 4-caroinal.last]; 

Sets the current input focus to be in this field and places the blinking caret before the 
specified character. If beforeChar is 0, puts the caret before the first character; if it is 
CAROINAllast or otherwise larger than the length of the backing string, the caret is placed 
after the last character in the field. Does not affect the current selection. 

SetReadOnly: procedure [f : Field, readonly: boolean] returns [old: boolean]; 

Changes the field's readonly attribute and returns its old value. If this field has the input 
focus and readonly is true, it clears the input focus and turns off the blinking caret. If this 
field has the selection and readonly is false and old is true, it sets the input focus to this 
field and places the caret after the last character in the selection. 

SetSeiection: procedure [f : Field, 
firstChar: cardinal 4-0, lastChar: cardinal 4-cardinallast]; 

Sets the current selection to be in this field, covering the specified range of characters. If 
firstChar is 0, the selection begins with the first character of the field. If lastChar is 
CAROINALLAST or Otherwise larger than the length of the backing string, the selection 
extends to the end of the string. Highlights the selection if it is not empty. Does not affect 
the input focus or caret. 

SetStreakSuccession: procedure [f : Field, new: SimpieT«xtDispiay.StreakSuccession] 
RETURNS [old: simpieT«xtDispiay.StreakSuccession]; 

Changes the field's StreakSuccession and returns the old StreakSuccession. Does not 
repaint the field. 

SetLosingFocusProc: procedure [fc: FieidContext, proc: LosingFocusProc]; 
LosingFocusProc: type ■ procedure [f : Field]; 

SetLosingFocusProc sets the LosingFocusProc for fc. proc is called whenever a field in fc 
loses the input focus, f is the field that is losing the input focus. This allows the client to 
undo things that were done when the input focus was set, such as clear softkeys. These 
items are defined in SimpleText£ditExtra.mesa. 

SetUseFinalRenderlngForms: procedure [fc: FieidContext, 
useFinalRenderingForms: boolean]; 

GetUseFinalRenderingForms: procedure [fc: FieidContext] 
returns [useFinalRenderingForms: boolean]; 

useFinalRenderingForms has meaning for languages in which characters are rendered 
differently at the end of a word than in the middle of a word, such as in Arabic. These 
items are defined in SimpleTextEditExtra2.mesa. 
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42.2.6 ChangeSizeProc 

ChangeSizeProc: type ■ procedure [f : Field, oldHeight, newHeight: integer, 
repaint: boolean]; 

Each FieidContext has a ChangeSizeProc associated with it. This procedure is called 
whenever any of its fields is redisplayed and the number of lines of text being displayed 
has changed. It may be called as a result of calling either RepaintField. TIPResults, or 
SetValue. The client is expected to update any affected data structures (such as the 
window.Ptace of other fields) and then optionally repaint any part of the window that is 
invalid. (There are two exceptions: the ChangeSizeProc is never called on a field for which 
CreateField was called with fixedHeight ■ true, and it is not called if both the old and new 
number of text lines require fewer vertical pixels than the height dims.h that was 
specified to CreateFieid.) 

The oldHeight and newHeight parameters are in vertical pixels. inOisplayProc is true if 
the ChangeSizeProc is being called as a result of calling RepaintField with repaint ■ true 
(that is» is being called indirectly by window. Val idate). 

If repaint is true, the ChangeSizeProc should not do a window. Validate, because this would 
cause undesirable recursion. 

42.2.7 Errors 

Error: error [type: ErrorType]; 

ErrorType: type ■ {fieldlsNopiace, noRoomIn Writer, lastCharGTfirstChar}; 

Error [fieidlsNopiace] is raised by GetBox, RepaintField, and TIPResults if SetPlace has 
never been called on the passed field. Error (noRoomIn Writer] is raised by CreateField, 
SetValue, and TIPResults if a non-NiL backingWriter was passed to CreateFieid, the 
backing Writer has a nil zone, and the desired operation would overflow the string. 

42.3 Usage/Examples 

42.3.1 Selection Management 

If certain atoms (PointOown, PointMotion, AdjustDown, AdjustMotion, CopyModeUp, 
MoveModeUp) are in the TiP.Results passed to TIPResults, SimpleTextEdit may become the 
manager of the current selection. The procedure SetSelection also causes SimpleTextEdit 
to manage the curent selection. 

While SimpleTextEdit is managing the current selection, it supports conversions to the 
following s«i«ction.Targets: shell, subwindow, length, and string. It also supports 
s«i«ction.Enumerate with a target of string. 

SimpleTextEdit implements the following Seiection.Actions:mark, unmark, clear, delete, 
clearlfHaslnsert, restore, and save. All other Actions are ignored. 

Selection. Act On [delete] automatically repaints the field that contained the current 
selection; the field may become taller or shorter, triggering a call on its ChangeSizeProc. 
Sel«ction.ActOn [delete] is a no-op if the current selection is in a readonly field. 
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42.4 Index of Interface Items 



Item 


Page 


ChangeSizeProc: type 


9 


CreateFieid: procedure 


3 


CreateFieldContext: procedure 


2 


Destroy Field: procedure 


4 


DestroyFieldContext: procedure 


2 


Error: error 


9 


ErrorType: type 


9 


Field: TYPE 


3 


FieldContext: type 


2 


FleidContextObject: type 


2 


FieldObject: type 


3 


GetBox: procedure 


6 


GetCaretPlace: procedure 


7 


GetOientData: procedure 


6 


GetFteldContext: procedure 


6 


GetFlushness: procedure 


7 


GetFont: procedure 


7 


GetinputFocus: procedure 


7 


GetReadOnly: procedure 


7 


GetStreakSuccession: procedure 


7 


GetUseFinal Render! ngForms : procedure 


8 


GetValue: procedure 


4 


GetWindow: procedure 


7 


GetZone: procedure 


7 


LosingFocusProc: type 


8 


RepaintField: procedure 


4 


SetOims: procedure 


7 


SetFixedHeight: procedure 


7 


SetFlushness: procedure 


7 


SetFont: procedure 


8 


SetlnputFocus: procedure 


8 


SetLosingFocusProc: procedure 


8 


SetPlace: procedure 


4 


SetReadOnly: procedure 


8 


SetSelection: procedure 


8 


SetStreakSuccession: procedure 


8 


SetUseFlnalRenderingForms: procedure 


8 


SetVaiue: procedure 


4 


TlPResults: procedure 


5 
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43.1 Overview 

The SimpleTextFont interface provides access to the default system font that is used to 
displayViewPoint's text, such as the text in menus, the attention window, window name 
stripes, containers, property sheet text items, and so forth. This interface is a 
specialization of the regular font management subsystem. 

43.2 Interface Items 

43.2.1 System Font 

MappedfontDescriptor: type; 

MappedFontHandle: TYPE ■ long pointer to MappedFontOescriptor; 

MappedFontOescriptor is an opaque type that contains all of the information about a font. 
(All metrics, including the width of each character, are in screen dots, not micas.) 

MappedOefauitFont: procedure returns [MappedFontHandle]; 

MappedDefauitFont returns the client a handle onto the system default font. May raise 
FontNotFound or Probiem[badFont]. The implementation of SimpleTextFont expects that 
the default font is available in the system file catalog, with the name System. No vaFont. 

MappedFont: procedure [name: xstrmg. Readers nil] 
returns { MappedFontHandle]; 

MappedFont returns a handle onto the named system font. The file must be a child of the 
system file catalog. Supplying nil is the equivalent of calling MappedDefauitFont. May 
raise FontNotFound or Problem{badFont]. 

MappedFontFromReference: procedure [NSFiie.Reference] 
RETURNS [ MappedFontHandle]; 
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MappedFontFromReference returns a handle onto the specified font file. May raise 
Problem[baciFont]. This is defined in SimpleTextFont£xtra2. mesa. 

UnmapFont: procedure [MappedFontHandle]; 

Unmaps a font that was mapped with MappedFont or MappedFontFromReference. 
UnmapFont is defined in SimpieTextFontExtra.mesa. 

43.2.2 Client-Defined Characters 

AddClientDefinedCharacter: procedure [ 
width, height: cardinal, 
bitsPerLine: cardinal, 

bits: LONG POINTER, 

offsetintoBits: cardinal <- 0 ] 
RETURNS [xstring.Character]; 

AddCiientOefinedCharacter adds the client's bitmap to the system font as a new character 
and returns the 16-bit value of the character position it is assigned. offsetintoBits is a byte 
offset. The new character's TextBIt flags indicate that it is neither a stop nor a pad 
character. At start-up time, at least 100 slots are available for these new characters. [0,26 1 
normally displays as the blob character. May raise 
Problem[clientCharacterBitsExhausted] or Probiem(clientCharacterCodesExhausted]. If 
RESUMEd, the character [0,26] is returned. 

The Xerox Character Code Standard sets aside a block of character codes for user 
definition. (See the Xerox Rendering Code Standard^ XSIS 068208, page 6.) In Star, it is 
often useful to include a small picture, for example, a 13x13 icon drawing, within a 
message or other text. 

The AddClientDefinedCharacter procedure provides a convenient way of presenting such 
small pictures within formatted system text. You create a character for the picture, say in 
initialization code, and then simply use that (16-bit) character within ordinary text 
sequences, such as window titles. 

43.2.3 Signals and Errors 

FontNotFound: signal [name: xstring. Reader]; 
If FontNotFound is resumed, the system font is used. 
Problem: signal [code: ProblemCode]; 
ProbiemCode: type > 

{badFont, clientCharacterCodesExhausted, clientCharacterBitsExhausted}; 

43.3 Usage/Examples 

SimpleTextFont is a specialization of the regular font management subsystem. 
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The font file format is easily parsed, it can be mappable into read-only virtual memory for 
use, and it can be extended. A single file defines the bitmaps for the Xerox characters in 

one font face and one font size, such as Bodoni Italic 10. Fine point: In the case in which several 
different font face/sizes have the same pictures, as can occur with some printwheel fonts, use the same file for 
more than one font/face. This subject is outside the scope of this specialized interface, because we are only dealing 
with one font. 

The font file begins with a header that identifies the font and describes the subsequent 
sections. Each subsequent section then contains TextBlt-style information about one 
character set's characters. Fine point: Descriptions of the font management subsystem and the ViewPoini 
font format are to be found elsewhere. 

43.3.1 Adding a Client- Defined Character 

The following example creates a small (13x13) icon and displays it as part of a string: 
my Bits: array [0..13) of word <- [-some bits--l; 

wb: xstring.WriterBody «-xstring.WriterBodyFromSTRiNG[" is an icon."]; 
smailPicture:xstring.Character <- simpieTextFont-AddClientOef inedCharacter [ 

width: 13, 

height: 13, 

bitsPerLine: 16, 

bits: @myBits, 

offsetlntoBits: 01; 

xstring.AppendChar(to: @wb, c: smallPicture]; 

[] <-SimpleTextDispiay.StringlntoWindow [ 
string: xstring.ReaderFromWriter[@wb], 
window: window, 
place: place]; 

43.3.2 Acquiring the System Font 

The following example acquires a handle to the system font: 

systemFont: simpieTextFont-MappedFontHandle ■ simpieTextFont.MappedFont[]; 
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43.4 Index of Interface Items 



Item Page 

AddCiientDefinedCharacter:PR0CE0URE 2 
FontNotFound: SIGNAL 2 
MappedDefaultFont:PROCEOURE 
MappedFont: PROCEDURE 
MappedFontOescriptor:TYPE 
MappedFontFrom Reference : procedure 
MappedFontHandle:TYPE 
Problem: SIGNAL 2 
ProblemCoderTYPE 2 
UnmapFont: procedure 2 



SoftKeys 



44.1 Overview 

The SoftKeys interface provides for client-defined function keys designated to be the 
isolated row of function Iteys at the top of the physical keyboard. It also provides a 
SoftKeys window whose '*keytops" may be selected with the mouse to simulate pressing 
the physical key on the keyboard. Such a window will be displayed on the user's desktop 
whenever an interpretation other than the default SoftKeys interpretation is in effect. 
(The default is assumed to be the functions inscribed on the physical keys.) 

44.2 Interface Items 

44.2.1 Data Structures for SoftKey Labels 

numberOf Keys: cardinal « . . . ; - This number is dependent on ttte physical Iceyboard. 

Represents the number of keys in the soft key row. Important: in SoftKeys. mesa, 
numberOfKeys is defined as a constant 8. This constant should not be used. Use the 
SoftKeysExtra.mesa numberOfKeys public variable. 

LabelRecord: type a record ( 

unshifted: xstnng.ReaderBody «-xstring.nuilReaderBody, 
shifted: xstring.ReaderBody xstring.nuiiReaderBody]; 

LabelRecord provides a record of two xstring.ReaderBody arrays so that both the shifted 
and unshifted key meanings may be labeled. It is expected that any individual key will 
have either a single unshifted label centered on the picture of the appropriate keytop, or 
both shifted and unshifted labels painted in two lines on the keytop, or no label at all 
(xstring.nullReaderBody for both shifted and unshifted). 

Labels: type « long descriptor for array of LabelRecord; 

Client-owned array of strings to be used as labels on the SoftKeys virtual keytops. The 
SoftKeys procedures expect an array of up to numberOfKeys LabelRecord's at a time. 
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Clients should see to it that string deallocation does not occur between calls to create and ^"1 
delete a SoftKeys instance. 

Bitmaps may be specified for individual labels by using 
SimpieTextFont.AddClientOefinedCharacter. The current SimpleTextFont implementation 
has a somewhat limited number of available slots for client-defined keys. (See the 
SimpleTextFont interface for more information.) 

44.2.2 Creating and Deleting SoftKeys 
Push: PROCEDURE [ 

tabie:TiP.Tabie4-Niu 
notif yProc: tip. Notify Proc nil, 
labels: Labels*- NIL, 
hIghlightedKey: cardinal <- nullKey, 
outlinedKey: cardinal <- nullKeyj 
RETURNS[window: window.Handlej; 

Push installs the SoftKeys interpretation in the following way: (1) If there is a non-NiL 
table, it is installed in the tip watershed (see TIPStar); (2) if there is a non-NiL notif yProc, it 
is attached to NormalKeyboard.TIP. The latter has the effect of passing all productions 
matched in NormalKeyboard.TIP to your notifyProc. (See Appendix A for a complete listing of 
NormalKeyboard.TIP.) 

A SoftKeys window is displayed by using labels to "inscribe" the keytop pictures with the 
new names of the keys. Both the shifted and unshifted state of a key may be labeled. If 
only the unshifted state is relevant, the shifted state may be defaulted to 
xstring.nullReaderBody. If there are fewer strings than keytops needing them, the 
remaining keys are left blank. Extra strings are ignored. Fine point: Bitmaps may be placed on the 
keytops by using simpiaTMtFont.AddCIientOefinedCharacter. Storage for the label strings is the 
responsibility of the client. Care should be taken to ensure that this storage is kept intact 
between a Push and a Remove of any given SoftKeys interpretation. 

outlinedKey and highlightedKey appear highlighted and/or outlined when the window is 
initialized. The default is no outlining or highlighting. Key values assume zero indexing 
[O..SoftKeysExtra.numberOfKeys). ( That is, the key marked Center is key 0, Bold is key 
l,and so forth.) 

Push returns a handle to the client's SoftKeys window. Note: There may be more than 
one SoftKeys window, with each client holding the handle to his own. The last Pushed 
interpretation is the one in effect until it is Removed or superseded by another Push. 

Remove: procedure [window: window.Handle]; 

The Remove procedure removes the SoftKeys interpretation and associated SoftKeys 
window. The client is responsible for removing its SoftKeys interpretation when it 
relinquishes control of the selection/input focus [see Selection interface descriptions of 
ActOn and Clear] or the user's attention (as in the case of the keyboard and font keys). A 
SoftKeys window and its associated SoftKeys interpretation constitute a unique SoftKeys ^"•l 
instance. Any SoftKeys instance may be removed from the stack of SoftKeys instances in 
an order other than the order pushed. 
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Attempts to Remove without the corresponding valid window handle from a Push result 
in the error InvalidHandle. 

Fine point: Ramove, rather than Pop. was chosen to describe the function opposite Push to clarify that this is not 
a true stack. While Push, as the name implies, acts on the top of the stack. Remove does not. It is possible to 
Remove a SoftKeys window from other than the top of the stack. 

Swap: PROCEDURE [ 

window: window.Handte. 
table: TiP.Tabie4-NiL. 
notifyProc: Tip.NotifyProc «-nil, 
labels: LabelS4-NiL. 
highlightedKey: cardinal 4-nuliKey, 
outiinedKey: cardinal null Key]; 

The Swap procedure is a way to exchange SoftKeys interpretations without changing the 
SoftKeys instance. Current examples of use include the keyboard key implementation 
where pressing the More key brings up another group of SoftKeys choices. It is strongly 
suggested that a client utilizing a More key place it on the first soft key (the key marked 
CENTER on the physical keyboard) for a consistent user interface. 

At the time when no SoftKeys interpretation is desired, a single Remove corresponding to 
the original Push is expected. Any number of Swaps may occur in between. Attempts to 
Swap without the corresponding valid window handle from a Push result in the error 
InvalidHandle. 

44.2.3 Highlighting and Outlining a SoftKeys Keytop Picture 

HighlightThisKey: procedure [ 
window: window.Handle 
key:cAR0iNAL 4-nullKey]; 

OutlineThisKey: procedure [ 
window: window.Handle, 
key: cardinal «- null Key]; 

These procedures are provided for those clients where permanent highlighting and/or 
outlining of certain soft keys is desired. (Do not confuse these procedures with the 
highlighting done when a key is selected with the mouse. That highlighting is done 
without client participation.) The first parameter, window, refers to the client's SoftKeys 
window returned from a Push. The cardinal corresponds to the key (zero indexing) to be 
outlined or highlighted whenever the chosen key changes. A key value of null Key undoes 
a key that is currently highlighted (or outlined). A number other than nuilKey or 
[O..SoftKeysExtra.numberOfKeys) results in NoOp. 

Attempts to call HighlightThisKey or OutlineThisKey without a valid handle from a Push 
result in the error InvalidHandle. 

nullKey: cardinal > last(cardinal]; 

A default value meaning no key, to be used for outiinedKey and highlightedKey. 
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44.2.4 Retrieving Information About a SoftKeys Window Instance 

Info: PROCEDURE [ 

window: window.Handle] 

RETURNS [ 

table: Tip.Table. 

notify Proc: tip. Notify Proc, 

labels: Labels, 

hlghlightedKey:CAROiNAL, 

outlinedKey:cAROiNAL]; 

The info procedure returns information relevant to the SoftKeys instance related to 
window. If the window handle is not valid, the errorlnvalidHandle is returned. 



44.2.5 Errors 

InvalidHandie: error: 

This error is raised if the SoftKeys window handle passed to Remove, Swap, Info, 
HighiightThisKey, or OutlineThisKey is invalid. 

44.3 Usage/Examples 

44.3.1 Graphics Example 

"When the selection is such that the graphics code talces control. 
" the initial graphics code should put up the graphics soft keys: 
graphicsSoftKeysWindow <~Push( 

table: graphicsSoftKeysTIPTable, 

labels: graphicsSoftKeyLabeis]; 

-where the core of the graphics tip. Table looks something like: 
--left-side values are defined in the LeveilVKeys interface 

SELECT TRIGGER FROM 

CenterDown « > Stretch; 

BoldDown > > Magnify; 

ItaiicsOown « > Grid; 

CaseDown, UnderlineOown a > Line; 

ObkUnderlineOown, SuperscriptOown ■ > Curve; 

StrikeoutOown, SubscriptOown « > Join; 

SuperSubOown, SmallerOown » > Top; 

endcase; 

-and part of the graphics tip. Notif yProc resembles the following: 
—left-side values are the atom results from the tip. Table 
atom => select result FROM 

Stretch »> DoMy Stretch Routined; 

Magnify a> OoMyMagnifyRoutine{]; 

Grid s> OoMyGridRoutineH; 

Line >> OoMyLineRoutinen; 

Curve »> DoMyCurveRoutineG; 
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Join * > DoMyJoinRoutineH; 
Top a > OoMyTopRoutined; 
enocase; 

"When graphics loses the selection, it must dear away its SoftKeys interpretation. 
RemoveigraphicsSoftKeysWindow): 

A client using More as one of its soft keys handles it in hits s tip. Tables and Tip.NotifyProc: 

TiP.Table entry: 

Center Down * > More; 

NotifyProc entry: 
More a > Swap[ 
window: my SoftKeys Window, 
table: myNextSoftKeysTiPTable, 
labels: myNextSoftKeyLabels, 
highlightedkey: 1]; 

This entry results in an exchange of the client's last SoftKeys interpretation for the next 
one specified, (namely, the installation of the new TiP.Table and new labels on the keytops.) 
The second key (bold on the physical keyboard) is highlighted in the SoftKeys window. 
The outlinedKey parameter has been left blank. This defaults to nullKey, in which case no 
key will be outlined. 

44.3.2 Keyboard Manager Example 

This client's (Keyboard Manager) SELECT arm does the right thing for both the 8010 and 
6085 workstation keyboards. 

atom ■> SELECT Z.a FROM 

CenterOown « > IF more then softKeys.Swap [] else Install Keyboard [labeH]; 
BoldDown » > Install Keyboard [Iabel2]; 
ItalicsOown a > InstailKeyboard [Iabel3]; 
CaseOown, UnderlineDown ■ > InstailKeyboard [labelA]; 
ObkUnderlineOown, SuperscriptOown « > InstailKeyboard [labels]; 
StrikeoutOown, SubscriptOown « > InstailKeyboard [Iabel6]; 
SuperSubOown « > InstailKeyboard [label?]; — No label? if the machine is an 

8010. 

ObkSmallerOown ■ > InstailKeyboard [labels]; — No labels for 8010 either. 
MarginsOown, SmallerOown ■ > ShowKeyboard []; 
FontDown, DefaultsOown ■ > SetKey board []; 

If the user presses the Margins Down on a 6085 or the Smaller Down on an 8010, he has 
actually invoked the soft key that is labeled SHOW in the soft keys window visible on the 
screen. 
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44.4 Index of Interface Items 



Item Page 

HighiightThisKey: procedure 3 

InfO: PROCEDURE 4 

InvalidHandle: error 4 

Label Record: type 1 

Labels: type 1 

nullKey: cardinal 3 

numberOf Keys: cardinal 1 

OutlineThisKey: procedure 3 

Push: procedure 2 

Remove: procedure 2 

Swap: PROCEDURE 3 



StarDesktop 



45.1 Overview 

The StarDesktop interface provides access to assorted facilities related to the ViewPoint 
desktop. 

45.2 Interface [terns 

45.2.1 General 

AddReferenceToOesktop: procedure [ 
reference : NSFii«. Reference , 
place:wtndow.Place <- nextPlace]; 

nextPiace: window.Place « [-l.-l]; 

Adds an icon to the desktop. The file (reference) must be a child of the desktop file (see 
GetCurrentDesktopFile below.) If there is already an icon at place, the next available 
place is used. 

GetPlaceFromReference: procedure [ref : NSFiie.Reference] 

RETURNS [Window.Place]; 

This returns the location of an icon on the desktop. It may be used with 
AddReferenceToOesktop to place an icon near another icon by passing the return value 
from GetPlaceFromReference to AddReferenceToOesktop. AddReferenceToOesktop 
places the new icon at the next available spot after the place passed in. 

SelectReference: procedure [reference: NSFiie.Reference] 
RETURNS [ok: boolean]; 

Selects the icon associated with the specified reference. SelectReference returns false if 
selection fails (for example, if the reference is not found on the desktop). Each call to 
SelectReference adds that reference to the selection (like doing an extended selection with 
adjust). To select a single icon, call Seiection.Clear followed by a SelectReference. 
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GetWindow: procedure returns [window: window. Handle]; 

Returns the desktop window (that is, the root window for ViewPoint). 
GetShellFromReference: procedure [ref : NSFiie.Reference] 

RETURNS [SWS: StarWindowShell.Handle]; 

If an icon has a shell currently opened, GetShellFromReference returns this shell. 

CreateOesktop: procedure [name: xstring. Reader] 
RETURNS [fh: NSFiie.Handle]; 

Creates a new desktop directory and returns a handle to it. name is typically a fully 
qualified three-part user name. It is used by logon plug-in clients, a friends-level facility 
(as opposed to a public facility). 

GetCurrentOesktopFile: procedure returns [NSFiie.Reference]; 

Every available desktop is an NSFIIe with attrlbute.isOlrectory a true. Desktops have 
children that are also NSFiles and show up as icons on the desktop (see Chapter 3 for more 
information). GetCurrentOesktopFile returns the NSFiie.Reference for the desktop NSFile 
that is currently installed and displayed to the user. 

GetNextUnobscuredBox: procedure [height: integer] returns [window.Box]; 

GetNextUnobscuredBox returns: the next available vertical segment of the desktop 
window of height, height, and width the width of the desktop. It is intended for such 
things as the Attention window and the typing feedback window. There is no guarantee 
that the box returned will be visible (that is,the client must ensure that the returned box 
is within the desktop window). 

SetDisplayBackgroundProc: procedure [procedure [window.Handle] ]; 

SetDispiayBackgroundProc allows a client to change the procedure that displays the 
background for the desktop. 



desktopWindowAvailable "DesktopWindowAvailable": Event notified when 

the desktop window has been initialized and inserted 
into the window tree. Cannot be vetoed. 



45.2.2 Atoms 



Several ATOMs are exported by the StarDesktop: 



attemptingLogoff 



"AttemptingLogoff": Event just before logoff. Can be 
vetoed. Gives clients a chance to veto logoff. 



fuilUserName 



"FullUserName": This atom is to be used with 
AtomicProfile. 
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newkon 

logoff 
logon 

userPassword 



"Newlcon": Event notified when an icon has been 
added to the desktop, either by user copy/move or by a 
client call to AddReferenceToOesktop. 

"LogofT*: Event occurs after logoff. Cannot be vetoed. 

"Logon": Event notified after successful ViewPoint 
logon. Cannot be vetoed. EventData is NSFIIe.Handle 
for the desktop file. 

"UserPassword": Also to be used with AtomicProfile. 



45.3 Usage/Examples 



45.3.1 Adding a Reference to the Desktop 

BuildFile: procedure ["parms—] ■ { 
reference: NSFiie. Reference 

InitializeFile [parent: starOesktop-GetCurrentOesktopFilen ]; - local proc 
place :winciow.Place [...]; 



starOesktop-AddReferenceToOesktop [reference, place]; 

}; 
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45.4 Index of Interface Items 



Item Page 

AddReferenceToOesktop: procedure 1 

attemptingLogoff : Atom.ATOM 2 

CreateOesktop: procedure 2 

desktopWindowAvaiiabie: Atom.ATOM 2 

fullUserName: Atom.ATOM 2 

GetCurrentDesktopFile: procedure 2 

GetNextUnobscuredBox: procedure 2 

GetPlaceFromReference: procedure 1 

GetSheilFromReference: procedure 2 

GetWindow: procedure 2 

nextPtace: constant 1 

newlcon: Atom.ATOM 3 

SetDispiayBackgroundProc: procedure 2 

SelectReference: procedure 1 

Logoff: Atom.ATOM 3 

Logon: Atom.ATOM 3 

userPassword: Atom.ATOM 3 
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46.1 Overview 

StarWindowSheii allows a client to create a Star-like window. A StarWindowShell 
window has a header that contains a title, commands, and pop-up menus. It may have both 
horizontal and vertical scrollbars. It has interior window space that may contain anything 
the client desires (see Figure 46.1.) StarWindowShell also supports the notion of "opening 
within." The client is insulated from the implementation-specific details of exactly how 
these features are represented on the display as well as how windows are arranged on the 
screen (for example, whether they overlap). 

46.1.1 Client overview 

A StarWindowSheii is a window (see Window interface) that is a child of the desktop 
window. A StarWindowShell has an interior window that is a child of the 
StarWindowShell and is exactly the size of the available window ispace in the shell ( that 
is, the StarWindowShell minus its borders and header and scrollbars). The interior 
window may have child windows created by the client. These children of the interior 
window are called body windows. The client may create an arbitrary number of body 
windows and may arrange them arbitrarily. Note: Because the body windows are children 
of the interior window, they are clipped by the interior window. A client could, for 
example, create a body window that is very much taller than the interior window and 
accomplish scrolling simply by sliding the body window around inside the interior window 
(This is what the default StarWindowShell scrolling does; for more detail, see the section 
on scrolling). 

The StarWindowShell interface provides a number of facilities for manipulating 
StarWindowShells and their various parts: creating and destroying a StarWindowShell; 
using body windows, commands and pop-up menus; client TransitionProcs (called 
whenever a StarWindowShell changes state—is opened or closed, for example); scrolling ; 
AdjustProcs and LimitProcs; and displaying and stacking (that is, open-within) 
StarWindowShells. The most commonly used facilities (creating a StarWindowSheii and 
body windows) are described here and in the section on interface items. The less commonly 
used facilities are described in each subsection of the interface items. 



46-1 



StarWindowShell 



Commands 



Header — 



J3s 



Close 



Title 



i 



Pop-up menus 



Vertical 
Scrollbar 



Interior 




46.1.2 Creating a StarWindowShell, Handles, etc. 

A StarWindowShell is created by calling starWindowShell.Create. There are no required 
parameters, but it is quite common to provide a name and a transitionProc. The name is 
displayed as the title in the StarWindowShell header. The transitionProc is called 
whenever the StarWindowShell is opened, destroyed, or "put to sleep," giving the client an 
opportunity to allocate and deallocate storage, open and close files, and so forth. 

StarWindowShell. Create returns a StarWindowSheli.Handle. A StarWindowShell. Handle is a 
RECORD [window.Handle]. Thus any procedure that takes a window. Handle also takes a 
StarWindowSheli.Handle, but not the other way around. (The Mesa compiler automatically 
strips off the brackets and passes the window.Handle if a StarWindowSheli.Handle is passed). 
In particular, a context may be hung directly off a StarWindowShell (see the Context 
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interface). The Handle returned by Create is then used as the first parameter to most other 
calls to StarWindowSheli. 

The StarWindowSheli returned by Create is not displayed on the screen (that is, it. is not 
inserted into the visible window tree). A StarWindowSheli may be inserted into the 
window tree by calling StarWindowSh«il.Push. This is usually not done by the client but 
rather by some other part of Viewpoint, such as the desktop implementation. For example, 
when the user selects an icon and presses OPEN or prof>s, the application (actually the 
application's Containe«.GenericProc) creates a StarWindowSheli and returns it. The 
desktop implementation then displays the StarWindowSheli by doing u 
StarWindowShell.Push. 

46.1.3 Body Windows 

Body windows are created by calling StarWindowSheli. CreateBody. This returns a 
window.Handle. The client can create an arbitrary number of body windows. Each body 
window is a child of the StarWindowShell's interior window. The body windows may 
overlap or not. They can actually be in any arrangement the client finds useful. Some 
common arrangements of body windows are as follows: 

• One very long body window. 

This is easy to scroll by simply sliding the body window, which is what the 
StarWindowSheli default scolling does. 

• One body window with BodyWindowJustFits « true. 

This is one way to display an infinite amount of data, such as a Tajo-like editor. The 
client must keep track of what is currently in the window, use adjust procedures, do 
scrolling, and so forth. This is difficult to implement 

• Several body windows about the size of the interior, adjacent, non-overlapping. 
This is another way to display an infinite amount of data. The client lets 
StarWindowSheli do default scrolling, which slides the body windows up or down and 
then calls the client to supply more body windows when it runs out. The client might 
put one page of text into each body window, supplying pages to StarWindowSheli 
scrolling as needed. 

• Several body windows smaller than the interior, adjacent, non-overlapping. 
This can be used to simulate subwindows. 

Note: Body windows can themselves have child windows, and so on. A client might 
implement frames in a document editor by making each frame a child of a body window. 

The eldest body window may be obtained by calling StarWindowShell.GetBody. All the body 
windows may be enumerated by calling starWindowSheli.EnumerateBodieslnOecreasingY or 
StarWindowSheli.EnumerateBodieslnlncreasingY. To get the StarWindowSheli from any 

body window, use StarWindowShell.ShellFrOmChild. Fine point: The client's body window.s may not be 
the only child windows of the interior window, and the interior window may not be the only child of the 
StarWindowSheli window. Therefore the client should never try to enumerate body windows by calling 
window.GetChild and window.GetSibiing starting with the StarWindowSheli, and the client should never try to get 
the StarWindowSheli from a body window by calling window.GetParent. 
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The client may provide a repaintProc and a bodyNotifyProc with each body window. The 
repaintProc is the display procedure that is called by the window implementation 
whenever part or all of the window needs to be displayed (see window.SetDlsplayProc). The 
bodyNotifyProc is a tip. Notify Proc that is attached to the window along with the normal 
set of TIP tables and receives notifications for the window (see 
TiP.SetNotifyProcAndTable). Note: If the client is going to use some ViewPoint interface 
to turn the body window into a particular type of window (such as FormWindow or 
ContainerWindow), these procedures should not be supplied by the client, but rather are 
supplied by that interface. 

A single body window can be set to fit into the interior window. Any time the 
StarWindowShelTs size is changed, the body window's size is changed accordingly. (See 
SetBodyWindowJustFits.) 



46.1.4 Commands and Menus 



Every StarWindowShell can have commands and pop-up menus, as in Figure 46.1. 
Commands are actually individual menu items (MenuOata.ltemHandle), where the 
MenuOata.ltemName appears with a rounded corner box around it. When the user elicits 
over a command, the MenuOata.MenuProc for that item is called. Commands are specified 
by calling starWindowSheii.SetReguiarCommands, which takes a MenuOata.MenuHandle. 
Each item in the menu is displayed as a command on the left side of the header. 

A pop-up menu is an entire menu. The menu's title appears with a rounded corner box 
around it on the right side of the shell's header. When the u.ser buttons down over the 
menu's title, a small window appears next to the poimter with one line for each menu 
item. When the user selects one of the items, that item's MenuOata.MenuProc is called. Pop- 
up menus are specified by calling StarWindowShell-AddPopupMenu. 

Facilities are also provided for specifying commands that should appear when a shell has 
other shells opened on top of or within it. (See the section on Push and Pop for a full 
discussion of the "open within" illusion, and the section on commands and menus for a full 
discussion of these extra commands.) 

46.2 Interface Items 

46.2.1 Create a StarWindowShell, etc. 



Create: procedure [ 

transitionProc: TransitionProc *- nil, 
name:xstring.Reader <- nil, 
namePicture:xstring.Character <- xchar.null, 
host: Handle *- nil, 
type: ShellType regular, 
sleeps: boolean <- false, 
considerShowingCoverSheet: boolean <- true, 
currentlyShowingCoverSheet: boolean <— false, 
pushersAreReadonly: boolean false, 
readonly: boolean false, 
scrollData: ScrollOata <- vanillaScrollData, 
garbageCollectBodiesProc: procedure [Handle] «-nil. 
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isCloseLegalProc: IsCloseKegalProc 4-niu 
bodyGravity: window. Gravity *- nw, 
zone: uncounted zone <- nil] 
RETURNS [Handle]; 
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Create makes a StarWindowSheli and returns a Handle to it. The StarWindowShell 
returned by Create is not displayed on the screen (is not inserted into the window tree). A 
StarWindowSheli may be inserted into the window tree by calling starWindowSheii.Push. 
This is usually not done by the client but rather by some other part of ViewPoint, such a.s 
the desktop implementation. For example, when the user selects an icon and presses opkn 
or PROPS, the application (actually the application's Containee.GenerlcProc) creates a 
StarWindowShell and returns it. The desktop implementation then displays the 
StarWindowShell by doing a StarWindowSh«il.Push. 

transitionProc is a procedure that is called whenever the state of the shell is about to 
change. In particular, it is called just before the shell is destroyed. The client uses a 
transitionProc to free any data structures that may have been allocated and associated 
with the shell. TransitionProcs are discussed in later in this chapter. 

name appears as the title in the header of the StarWindowShell. 

namePicture appears just before the title in the header. This character is usually a small 
icon picture created by simpieTextFont.AddClientDef inedCharacter. 

host is a StarWindowShell that this shell is logically attached to. The host shell is not 
destroyed while this shell is open. This is typically used by property sheets to indicate the 
shell that the property sheet is displaying properties of. If host is nil, closing this shell does 
not depend on any other shell. 

type is the type of the shell. Shell placement algorithms may be affected by the type. For 
example, regular shells will not overlap when displayed with Star-style window 
management, while psheet shells may overlap other shells. 

sleeps indicates whether this shell can go into the sleeping starWindowSheil.State. If it is 
FALSE, we assume that the client .software does not take advantage of the possibilities of the 
sleeping State (by remembering data from open to open). This argument is used with the 
client's transitionProc, discussed later in this chapter. 

considerShowingCoverSheet and currentlyShowingCoverSheet indicate whether the 
shell should ever possess a cover sheet and, if so, whether the cover sheet should be visible. 
What appears in any cover sheet is governed by a cover sheet implementation. See the 
section on Errors. 

The two readonly arguments define whether this shell is uneditable and whether all 
shells pushed onto this one should be uneditable. readonlyness is really up to client 
interpretation. This information is simply maintained for client convenience. If a shell 
below this one in a push stack has pushersAreReadonly set true, then the implementation 
forces readonly to true. 

scrollOata indicates whether vertical or horizontal scrollbars should appear and allows the 
client to supply procedures to be called for various user scrolling actions. (See the section 
on scrolling for full details.) The default will cause vertical scrollbars to appear, but not 
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horizontal. The default scrolling procedures simply slide body windows up or down, left or 
right, as appropriate. 

garbageCollectBodiesProc is called when a scroll action causes a body window to be placed 
completely outside the shell's interior window. The call thus allows the client an 
opportunity to garbage-collect the body window and associated data structures. (See the 
section on scrolling.) 

isCloseLegaiProc is called when the user attempts to close the StarWindowSheil or when a 
client calls StandardClose, StandardCloseAll, or StandardCloseEverything. This allows 
the client to veto the user's attempt to close the window. If the isCloseLegaiProc returns 
TRUE, the shell is closed; if the IsCloseLegaiProc returns false, the shell is not closed. The 
isCloseLegaiProc is also a convenient way for the client to get control when the window Is 
being closed. 

bodyGravity argument indicates what value for gravity should be used when the 
implementation adjusts the size of a body window. 

zone argument specifies the zone from which all storage related to the shell is allocated, [f 

zone ■ NIL, StarWindowSheil provides its own zone. Fine point: The window.Objects themselves are 
not allocated out of the client's zone. If the client allocates child windows using a zone (window. Create ot- 
window.New with non-NIL zone), these child windows must be removed from the shell before it is destroyed. When 
the shell's TransitionProc is called with a state of dead, the client should remove those windows. 

Handle: type « record [window.Handle]; 

Create returns a Handle. Any procedure that takes a window.Handle also takes a 
StarWindowSh«il.Handle, but not the other way around. (The Mesa compiler automatically 
strips off the brackets and passes the Window.Handle if a StarWindowShell.Handle is passed). 
In particular, a Context may be hung directly off a StarWindowSheil (see the Context 
interface). The Handle returned by Create is then used as the first parameter to most other 
calls to StarWindowSheil. 

nullHandle: Handle > [nil]; 

nullHandle is provided as a convenience. 

IsCloseLegaiProc: type » procedure [sws: Handle, 
closeAII: boolean <- false] returns [boolean] ; 

cioseAll indicates whether the user selected Close or CloseAII. 

Destroy: procedure [ sws: Handle]; 

Destroys the StarWindowSheil and associated data. Calls the client's transitionProc with 
state = dead. May raise Error [notASWS]. 

ShellType: type a {reguiar(O), l<eyboard, psheet, attention, static, iast(15)}; 

ShellType influences how a shell behaves in several regards, regular sliulls have a ? 
command, a Close command, and a Close All command if opened on lop of another sholl 
With Star-like ovorall screen management, regular shoUs do not ovorlap: tho> c-haiii^e >i/.L 
whencve;r a window is opened or closed, psheet shells do not have any StarWindowShell- 
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supplied commands and freely overlap other shells. The PropertySheet interface uses 
psheet shells to create property sheets, static shells are exempted from any overall screen 
management; for example, a static shell is not shrunk to make room for a regular shell 
when the overall screen management is Star-like. Some clients may find this useful. Most 
clients do not use keyboard, psheet, or attention types. 

StandardCiose: procedure [sws: Handle] returns [Handle]; 

StandardCioseAli: procedure [sws: Handle] returns [Handle]; 

StandardCiose and StandardCioseAli provide procedural access to the Close and Close All 
commands that are placed in a shell's header automatically by StarWindowShell. These 
procedures call the client's isCloseLegalProc and transitionProc, just as if the user had 
selected the command. If StandardCiose or StandardCioseAli is not successful, the return 
parameter is the shell that did not close; otherwise, the return parameter is NIL. May raise 
Error [notASWS]. 

StandardCloseEverything: procedure returns [notClosed.: Handle]; 

StandardCloseEverything closes all open StarWindowSheils. Logoff uses this procedure. 
notClosed is the first window that could not be closed because its IsCloseLegalProc 
returned FALSE. All windows that can be closed will be. If notClosed is nil, then all windows 
are closed. 

NewStandardCloseEverything: public procedure 

RETURNS [numberLeftOpen: cardinal <-0. lastNotCIOsed: Handle <- nuilHandie]; 

This procedure is the same as StandardCloseEverything except that it also returns the 
number of shells that vetoed close. NewStandardCloseEverything is defined in 
Star Windo wShe 1 1 Extra, mesa. 

SetPref erred Dims: procedure [ sws: Handle, dims: window. Dims]; 
SetPreferredPlace: procedure [sws: Handle, place: wndow.Place]; 

SetPreferredDims and SetPreferredPlace provide a suggestion as to the desired size and 
location of the shell. Depending on the overall screen management in effect at the time the 
shell is displayed, these preferred values may be ignored. May raise Error [notASWS]. 

GetPreferredDims: procedure [ sws: Handle] returns [box: window.Dims ]; 

GetPreferredPlace: procedure [sws: Handle] returns [box: wndow.Place]; 

GetPreferredDims and GetPreferredPlace return the current preferred dims and place of 
sws. May raise Error [notASWS]. These are defined in Star Windo wShellExtra4. mesa. 

SetPreferredlnteriorDims: procedure [sws: Handle, dims: Window.Dims]; 

SetPreferredlnteriorDims makes the shell just big enough to fit around dims. This means 
the interior window will be of size dims. SetPreferredlnteriorDims is defined in 
StarWindowShellExtra2. mesa. 
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46.2. 1. 1 IsCloseLegalProc 

The client may supply an isCloseLegalProc when a StarWindowShell is created or later by 
calling SetlsCioseLegalProc. This client procedure is called when the user attempts to 
close the StarWindowShell or when a client calls StandardClose, StandardCloseAll, or 
StandardCloseEverything. This allows the client to veto the user's attempt to close the 
window. If the IsCloseLegalProc returns true, the shell is closed; if the IsCloseLegalProc 
returns FALSE, the shell is not closed. The IsCloseLegalProc is also a convenient way for the 
client to get control when the window is being closed. 

IsCloseLegai: procedure [ sws: Handle, cioseAli: boolean] returns [boolean]; 

IsCloseLegai calls the client's IsCloseLegalProc and returns the value returned from that 
call. If there is no isCloseLegalProc, IsCloseLegai returns true. May raise Error [notASWS]. 

IsCloseLegalProcReturnsFalse: IsCloseLegalProc; 

GetlsCloseLegalProc: procedure [sws: Handle] 
returns [ IsCloseLegalProc ]; 

GetlsCloseLegalProc returns the current IsCloseLegalProc associated with sws. May raise 
Error [notASWS]. 

SetlsCioseLegalProc: procedure [ 
sws: Handle, 
proc: IsCloseLegalProc ]; 

SetlsCioseLegalProc sets the IsCloseLegalProc for sws. May raise Error [notASWS]. 

Note: IsCloseLegalProc: type ■ procedure [... should be in this interface and will be added 
in the next release. 

46.2.1.2 Miscellaneous Get and Set Procedures 

Several procedures that set and return values logically associated with a 
StarWindowShell are provided. 

GetContainee: procedure [sws: Handle] returns [containee.Oata]; 
GetHost: procedure [sws: Handle] returns [Handle]; 
GetReadonly: procedure [sws:Handle] returns [boolean] ; 
GetType: procedure [sws:Handle]RETURNS[ShellType]; 

These procedures return the obvious value associated with sws. May raise Error 
[notASWS]. 

GetZone: procedure [sws: Handle] returns [uncounted zone]; 

The StarWindowShell implementation creates a zone when a StarWindowShell is created 
and uses the zone as storage for all shell-related items, such as name strings. The client 
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can use this zone, knowing that the zone is completely garbage-collected when the shell is 
destroyed. GetZone returns this zone. May raise Error [notASWS]. 

HaveOisplayedParasite: procedure [sws: Handle] returns [boolean]; 

HaveOispiayedParasite returns true if a shell is displayed that has this shell (sws) as its 
host. (See host under starWindowSheil.Create.) For example, if a property sheet that was 
created with host = sws is currently displayed, then HaveOisplayedParasite [sws] 
returns true. May raise Error [notASWS]. 

SetContainee: procedure [sws: Handle, file: containee.OataHandle]; 

SetHost: procedure [sws, host: Handle] returns [old: Handle]; 

SetName: procedure [sws: Handle, name: xstring. Reader]; 

SetNamePicture: procedure [sws: Handle, picture: xstring.Character]; 

SetReadOniy: procedure [sws: Handle, yes: boolean]; 

SetSleeps: procedure [sws: starwindowSheii.Handle, sleeps: boolean] 
RETURNS [old: boolean]; 

sleeps ■ TRUE means the shell can be put to sleep. It is the same as the sleeps parameter to 

Create. Fine point: This procedure isj currently exported through StarWindowSheilExtra. 

These procedures set the obvious value associated with sws. May raise Error [notASWS]. 

46.2.2 Body Windows 

A StarWindowShell is a window (see Window interface) that is a child of the desktop 
window. A StarWindowShell has an Interior window that is a child of the 
StarWindowShelland is exactly the size of the available window space in the shell (that is, 
the StarWindowShell minus its borders and header and scrollbars). The interior window 
may have child windows created by the client. These children of the interior window are 
called body windows. The client may create an arbitrary number of body windows and 
arrange them in an arbitrary fashion. Note: Since the body windows are children of the 
interior window, they are clipped by the interior window. A client could, for e.xample, 
create a body window that is very much taller than the interior window and accomplish 
scrolling by simply sliding the body window around inside the interior window. (This is 
actually what the default StarWindowShell scrolling does; for more detail, see the section 
on scrolling). 

Body windows are created by calling StarWindowShell. CreateBody. This returns a 
Window. Handle. The client can create an arbitrary number of body windows. Each body 
window is a child of the StarWindowShell's interior window. The body windows may 
overlap or not. They can be in any arrangement the client finds useful. Some common 
arrangements of body windows are as follows: 
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• One very long body window. 

This is easy to scroll by simply sliding the body window, which is what the 
StarWindowShell default scrolling does. 



• One body window with BodyWindowJustFits « true. 

This is one way to display an infinite amount of data, such as a Tajo-Iike editor. The 
client must keep track of what is currently in the window, use adjust procs, do 
scrolling, and so forth. This is difficult to implement. 

• Several body windows about the size of the interior, adjacent, non-overlapping. 
This is another way to display an infinite amount of data. The client lets 
StarWindowShell do default scrolling, which slides the body windows up or down and 
then calls the client to supply more body windows when it runs out. The client might 
put one page of text into each body window, supplying pages to StarWindowShell 
scrolling as needed. 

• Several body windows smaller than the interior, adjacent, non-overlapping. 
This can be used to simulate subwindows. 

Note: Body windows can themselves have child windows, and so on. A client might 
implement frames in a document editor by making each frame a child of a body window. 

CreateBody: procedure [ 
sws: Handle, 

repaintProc: PROCEDURE [window.Handle] «-nil, imii 
"bodyNotifyProc: TiP.NotifyProc «-NiL, 

box: window.Box <~ [[0,0],[0,29999]] ] RETURNS [window.Handlel; 

CreateBody creates a body window that is a child of the interior window of sws. 
repaintProc is the display procedure that is called by the window implementation 
whenever part or all of the body window needs to be displayed (see Window. SetDisplayProc). 
bodyNotifyProc is a TiP.NotifyProc that is attached to the window along with the normal 
set of TIP tables and receives notifications for the window (see TiP.SetNotifyProcAndTable 
and TiPStar.NormalTable). Note: If the client is going to use some ViewPoint interface to 
turn the body window into a particular type of window (such as FormWindow or 
Container Window), these procedures should not be supplied by the client but are supplied 
by that interface, box indicates the size and location of the body window within the shell's 
interior window. If box.dims.w and/or box.dims.h is zero, the body window takes on the 
dims.w and/or dims.h of the shell's interior window. May raise Error [notASWS]. 

DestroyBody: procedure [body: window.Handle]; 

OestroyBody destroys body and any Context data associated with it. May raise Error 
[notASWS]. 

GetBody: procedure [sws: Handle] returns [window.Handle]; 

GetBody returns the eldest body window of sws. The client's body windows may not be the 
only child windows of the interior window, and the interior window may not be the only ^gtut 
child of the StarWindowShell window. Therefore the client should never try to enumerate 
body windows by calling window. GetChild and window.GetSibling starting with the 
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StarWindowShell. The EnumerateBodiesXXX procedures should be used instead. May 
raise Error [notASWS]. 

SheliFromChild: procedure [child: window.Handle] returns [ Handle]; 

ShellFromChild returns the shell given any body window or any descendant window of the 
shell. The client's body windows may not be the only child windows of the interior window, 
and the interior window may not be the only child of the StarWindowShell window. 
Therefore the client should never try to get the StarWindowShell from a body window by 
calling window.GetParent. May raise Error [notASWS]. 

EnumerateBodieslnlncreasingY: procedure [ 

sws: Handle, proc: BodyEnumProc] returns [window.Handle <- nil]; 

EnumerateBodieslnOecreasingY: procedure [ 

sws: Handle, proc: BodyEnumProc] returns [window.Handle <- nil]; 

BodyEnumProc: TYPE ■ procedure [victim: window.Handle] 
returns [stop: boolean false]; 

The EnumerateBodiesln... procedures enumerate all the body windows of sws, calling proc 
for each body window until proc returns stop « true. EnumerateBodieslnlncreasingY 
enumerates the body windows in increasing order of window.GetBox [body]. place. y, and 
EnumerateBodieslnOecreasingY enumerates the body windows in decreasing order of 
Window.GetBox [body].place.y. Each procedure returns the last body window enumerated 
or NIL if all body windows were enumerated. These procedures are especially handy for 
clients that do their own scrolling. To minimize repainting when scrolling a set of body 
windows upward, it is important to move the upper ones first, and vice versa. May raise 
Error [notASWS]. 

GetBodyWindowJustFits: procedure [sws: Handle] returns [ boolean]; 
SetBodyWindowJustFits: procedure [sws: Handle, yes: boolean]; 

Some clients may wish to have a single body window that is automatically resized by the 
StarWindowShell implementation to just fit within the interior of the shell. Such a body 
window is said to have BodyWindowJustFits = true. If BodyWindowJustFits = false (the 
default for CreateBody), StarWindowShell leaves the body window's dimensions alone, 
even though the body window may stick out or not fill the shell. GetBodyWindowJustFits 
and SetBodyWindowJustFits allow the client to determine and set this just-fits behavior 
for a single body window. Setting just-fits when there is more than one body window yields 
undefined results. May raise Error [notASWS]. 

GetAvailableBodyWindowOims: procedure [sws: Handle] 
returns [window.Dims]; 

GetAvailableBodyWindowOims returns the current dimensions of the interior window of 
sws. May raise Error [notASWS]. 

IsBodyWindowOutOflnterior: procedure [body: window.Handle] 

RETURNS [boolean]; 
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isBodyWindowOutOf Interior returns true if any part of body is sticking out of the interior jpnn 
window of its shell. May raise Error [notASWS]. 

InstailBody: procedure [sws: Handle, body: window.Handle]; 

InstallBody installs a previously created window into a StarWindowShell, thus making 
the window a body window. Most clients do not need to use this procedure. May raise Error 
[notASWS]. 

OestallBody: procedure [ body: window.Handle]; 

DestallBody removes body from its StarWindowShell. Most clients do not need to use this 
procedure. May raise Error [notASWS]. 

46.2.3 Commands and Menus 

Every StarWindowShell can have commands and pop-up menus, as in Figure 47.1. 
Commands are actually individual menu items (MenuData.ltemHandle), in which the 
MenuOata.ltemName appears with a rounded corner box around it. When the user clicks 
over a command, the MenuOata.MenuProc for that item is called. Commands are specified 
by calling starWindowShelt.SetRegularCommands, which takes a MenuOata.MenuHandie. 
Each item in the menu is displayed as a command on the left side of the header. 

A pop-up menu is an entire menu. The menu's title appears with a rounded corner box 
around it on the right side of the shell'.s header. When the user buttons down over 
menu's title, a small window appears next to the pointer with one line for each menu item. 
When the user selects one of the items, that item's MenuOata.MenuProc is called. Pop-up 
menus are specified by calling starWindowShelLAddPopupMenu. 

The Window.Handle that is passed to the MenuOata.MenuProc for a command or pop-up 
menu item is the window.Handle for the StarWindowShell that the command or pop-up 
menu is currently displayed in. 

StarWindowShells that are of type regular (see StarWindowShell. ShellType) always have 
system commands leftmost in the header. When a shell is directly on the desktop, the 
system command is Close. When a shell is opened within another, the system commands 
are Close and Close All . 

Note: Commands may be added to and removed from a StarWindowShell by using 
MenuData.Addl tern, and so forth. 

The implementation automatically overflows the rightmost commands into an overflow 
pop-up menu when all of them will not fit in the header. If all the pop-up menus will not 
fit in the header, the leftmost items are overflowed into the rightmost pop-up menu. The ' 
rightmost pop-up menu is always guaranteed to be displayed, because shells are not 
allowed to be so small that no pop-up menu will fit. 

SetRegularCommands: procedure [ 

sws: Handle, commands: MenuOata.MenuHandie] ; ^laiii^ 

SetRegularCommands associates commands with sws. May raise Error [notASWS]. 



46-12 



Viewpoint Programmer's Manual 



46 



GetRegularCommands: procedure [sws: Handle] 
RETURNS [MenuData.MenuHandle]; 

GetRegularCommands returns the regular commands associated with sws. May raise 
Error [notASWS]. 

AddPopupMenu: procedure [ 

sws: Handle, menu: MenuData.MenuHandle] ; 

AddPopupMenu adds menu to the available pop-up menus in sws. The title of menu is 
displayed in the StarWindowShell header with the small pop-up menu symbol ( s ) just to 
the left of it, enclosed in a rounded corner box. Note: Any arbitrary symbol (less than the 
height of the system font) can be part of the title by using 
SimpieTextFont.AddCilentDefinedCharacter. May raise Error [notASWS]. 

SubtractPopupMenu: procedure [ 

sws: Handle, menu: MenuData.MenuHandle] ; 

SubtractPopupMenu removes menu from sws. May raise Error [notASWS]. 

EnumeratePopupMenus: procedure [sws: Handle, proc: MenuEnumProc]; 

Enumerates the pop-up menus associated with the shell. 

EnumerateAilMenus: procedure [sws: Handle, proc: MenuEnumProc]; 

Enumerates every menu visible in the shell. This includes pop-ups, regular commands, 
tOpPushee commands from the shell underneath, etc. Fine point: This procedure is currently 
exported througii StarWindowShellExtra. 

MenuEnumProc: type ■ procedure [menu: MenuData.MenuHandle] 
returns [stop: boolean <- false]; 

46.2.3.1 Pushee Commands 

Facilities are also provided for specifying commands that should appear when a shell has 
had other shells opened on top of or within it. These facilities are useful only to a client 
that implements some type of open-within capability, such as folders and file drawers. 
(See the section on commands and menus for a full discussion of the "open within" 
illusion.) These extra commands come in three sets: the set that should be displayed when 
this shell is just below the top of the install stack, the set that should be displayed when 
this shell is anywhere in the install stack, and the set that should be displayed if this shell 
is at the bottom of an install stack. These are the so-called TopPushee, MiddlePushee, and 
BottomPushee commands. 

Figure 46.2 depicts how these pushee commands, if supplied, will affect the commands 
visible in a given shell's header. In Figure 46.2, Shell B is Pushed on top of Shell A and 
Shell C is Pushed on top of Shell B. If Shell A is the only shell displayed. Shell A's system 
and regular commands appear in the shell's header. With Shell B Pushed on top of Shell A, 
Shell B's system and regular commands appear as well as Shell A's bottom pushee, middle 
pushee, and top pushee commands. This is because Shell A is on the bottom, in the middle, 
and just below the top of the stack of shells. With Shell C Pushed on top of Shell B, Shell 
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A's bottom pushee and middle pushee commands appear, but not Shell A's top pushee 
commands. Shell B's top pushee and middle pushee commands appear, but not its bottom 
pushee commands. 

Caution: The Window.Handle passed to the MenuOata.MenuProc for any pushee command 
is the Window.Handle of the StarWindowSheil that the command is currently displayed in, 
not the StarWindowSheil that the command was originally associated with. If the client 
wants to be able to recover the StarWindowSheil that the command was originally 
associated with, it may be saved as the MenuData.ltemOata. 

SetBottomPusheeCommands: procedure [ 

sws: Handle, commands: MenuOata.MenuHandle] ; 

SetMiddlePusheeCommands: procedure [ 

sws: Handle, commands: MenuOata.MenuHandle] ; 

SetTopPusheeCommands: procedure [ 

sws: Handle, commands: MenuOata.MenuHandle] ; 

GetPusheeCommands: procedure [sws: Handle] 

returns [bottom, middle, top: MenuOata.MenuHandle]; 

May raise Error [notASWS]. 
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A's system menu 
A's regular menu 



B's system menu 

B's regular menu 

A's bottom pushee menu 
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C's system menu 
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B's middle pushee menu 




B's top pushee menu 




A's bottom pushee menu 




A's middle pushee menu 


Shell B 






Shell C 



Figure 46-2. Install Stack of Window Shells 



46.2.4 Transition Procs 

A StarWindowShell is always in one of three states: awake, sleeping, or dead. The awake 
state indicates that the shell is currently displayed. The sleeping state indicates that the 
shell still exists but is not being displayed and therefore resources associated with the 
display state should be freed. The dead state indicates the shell is about to be destroyed 
and therefore all resources associated with it should be freed. 

Every StarWindowShell can have a client-supplied TransitionProc associated with it. This 
TransitionProc is called whenever the shell's state changes. The client may then do 
whatever is necessary in terms of allocating or freeing resources. 

The client may call starwindowSheil.Create [ ... sleeps: false ... ] to indicate that the 
application does nothing interesting with the sleeping state. This may cause routines that 
would otherwise put the shell in sleeping state (say on a close, where it might be quickly 
reopened) to put it in dead state instead. 
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State: type - {awake(O), sleeping, dead, last(7)}; jHH 
TransitionProc: type a procedure [sws: Handle, state: State]; 

The TransitionProc is a client-supplied procedure responsible for allocating or deallocating 
client data structures when sws's state changes, state is the new state of sws. 

GetSieeps: procedure[sws: Handle] returns [boolean] ; 

GetSleeps returns the value of the sleeps parameter that was passed to Create when sws 
was created. If true, then the application responsible for this shell can deal with the 
sleeping state. May raise Error [notASWS]. 

GetState: procedure [sws: Handle] returns [ State ] ; 

GetState returns the current state of sws. May raise Error [notASWS]. 

GetTransitionProc: procedure [sws:Handle] returns [TransitionProc] ; 

GetTransitionProc returns the current TransitionProc associated with sws. May raise 
Error [notASWS]. 

SetTransitionProc: procedure [sws: Handle, new: TransitionProc] 
returns [ old: TransitionProc] ; 

SetTransitionProc sets the current TransitionProc for sws and returns the old one. May ^""^ 
raise Error [notASWS]. 

SetState: procedure [sws: Handle, state: State] ; 

SetState sets the state of sws and calls the client's TransitionProc as appropriate. Most 
clients will not call this procedure. May raise Error [notASWS]. 

SleepOrOestroy: procedure [Handle] RETURNS[Handle]; 

SleepOrOestroy either puts the shell in the sleeping state or destroys the shell, depending 
on the value of the sleeps boolean that was passed to Create when the shell was created. If 
the shell has the ability to sleep (sleep s true), then the shell is put into the sleeping 
state; otherwise, the shell is destroyed. The same shell is returned if the shell was put in 
the sleeping state. This returned Handle should be kept somewhere for later use; 
otherwise, the shell will be lost. A nil handle is returned if the shell was destroyed. This 
procedure might be used by the desktop implementation when a shell is closed. May raise 
Error [notASWS]. 



46.2.5 Scrolling 

Only part of an object is usually visible to the user at any one moment in the interior of a 
StarWindowSheil. The user can request to see more of the object by scrolling the contents 
up or down inside the shell. The user can perform three kinds of scrolling by using the 
scrollbars pictured in Figure 47.1. (1) He can move the contents a little at a time by 
pointing at the arrows (up, down, left, right) in the scrollbars. (2) He can move the 
contents a page or screenful at a time by pointing at the plus ( + ) and minus (-) signs. 
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(3)He can jump to any arbitrary place within the entire extent of the object being viewed 
by pointing in the blank part of the vertical scrollbar (this latter operation is called 
thumbing). 

StarWindowSheil provides various levels of support to a client for performing these 
scrolling operations. The client can allow StarWindowSheil to do all the scrolling 
functions, the client can do some of them and leave the rest to StarWindowSheil, or the 
client can do all scrolling operations. Much of this decision will be based on how the client 
chooses to arrange body windows within the shell (see the section on body windows above 
and more discussion below). First, we will describe the various types of scrolling and 
scrolling procedures that a client can supply; then we will describe the default scrolling 
procedures provided by StarWindowSheil. 

In the simplest (for the client) case, one body window contains the entire extent of the 
object being viewed. StarWindowSheil can handle all scrolling in this case. The client 
simply defaults the scroll Data parameter in the call to StarWindowSheil. Create. When the 
user points at an arrow, StarWindowSheil moves the body window a small amount. When 
the user point at plus or minus, StarWindowSheil moves the body window by one interior 
window's height. When the user thumbs, StarWindowSheil will move the body window to 
an appropriate place based on its overall height. 

In a slightly more complex case, body windows are butted up against one another. When 
the user points at an arrow, StarWindowSheil moves all the body windows a small 
amount. When the user point at plus or minus, StarWindowSheil moves all the body 
windows by one interior window's height. When the user thumbs, StarWindowSheil 
moves all the body windows to an appropriate place based on the combined overall height 
of the body windows. However, in this case the client often does not have the entire extent 
of the object displayed in these body windows but rather wants to tack new body windows 
on each end as these body windows are scrolled off. The client can do this by providing a 
MoreScrollProc for the shell. StarWindowSheil calls the client's MoreScrollProc whenever 
it runs out of body windows. 

In the most complex case, the client has a single body window that "just fits" (see 
SetBodyWindowJustFits in the section on body windows), and only part of the entire object 
is displayed at any one time. The client must provide all the scrolling functions for this 
case. This means providing an ArrowScrollProc (to handle the user's pointing at the 
arrows, plus, and minus) and a ThumbScrollProc (to handle the user's thumbing). 

Of course, the client may provide its own scrolling procedures for any of the above cases, 
even the simple one, to override the type of scrolling that StarWindowSheil provides. 

Scroll Data: TYPE » record! 

display Horizontal: boolean ^ false, 
display Vertical: boolean <- false, 
arrowScroll : ArrowScrollProc «- nil, 
thumbScroll: ThumbScrollProc <- nil, 
moreScroll: MoreScrolllProc <- nil ]; 

ScrollData is passed to Create and SetScrotlData to specify the desired scrolling. 
displayHorizontal indicates whether the shell should have a horizontal scrollbar. 
displayVertical indicates whether the shell should have a vertical scrollbar. arrowScroll is 
called when the user points at the arrows or at the plus or minus signs. thumbScroll is 
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called when the user thumbs. These procedures are expected to perform the appropriate 
scroll, probably by moving body windows with Window.Slide. If either arrowScroil or 
thumbScroil are nil, StarWindowShell provides default scrolling procedures 
(VanillaArrowScroil and VanillaThumbScroll) that operate as described above. moreScroll 
is called when VanillaArrowScroil or VanillaThumbScroll needs more body windows to be 
supplied by the client. The client should never need to supply both an arrowScroil and a 
moreScroll. 

ArrowScrollProc: type « procedure [ 
sws: Handle, 
vertical: boolean, 
flavor: ArrowFlavor, 

arrowScroil Action: ArrowScroil Action <- go]; 
ArrowFlavor: type a (pageFwd, pageBwd, forward, backward}; 

An ArrowScrollProc is called whenever the user points at an arrow or the plus or minus 
sign in a scrollbar. The ArrowScrollProc is expected to scroll the contents of sws as 
appropriate, vertical indicates whether to scroll vertically (true) or horizontally (false). 
flavor indicates what type of scrolling the user requested; pageFwd means the user 
pointed at the plus sign (vertical « true) or the right margin symbol (vertical ■ false). 
pageBwd means the user pointed at the minus sign (vertical ■ true) or the left margin 
symbol (vertical > false), forward means the user pointed at the up-pointing arrow 
(vertical » true) or the left-pointing arrow (vertical « false), backward means the user 
pointed at the down-pointing arrow (vertical » true) or the right-pointing arrow (vertical 
» FALSE). The ArrowScrollProc wiil.be called repeatedly as long as the user has the mouse 
button down over one of the arrows, thus producing continuous scrolling. Note: 
EnumerateBodieslnincreasingY and EnumerateBodieslnOecreasingY are quite useful 
when scrolling body windows (see the section on body windows). 

ArrowScrollAction: type ■ {start, go, stop}; 

start indicates the user just buttoned down, go indicates the user still has the button 
down, stop indicates the user just buttoned up. This allows clients to scroll body windows 
without repainting until the ArrowScrollProc is called with arrowScroil Action « stop. 

ThumbScrollProc: type » procedure [ 
sws: Handle, vertical: boolean, flavor: ThumbFlavor, m, outOfN: integer]; 

ThumbFlavor: type a {downClick, track, upClick}; 

A ThumbScrollProc is called whenever the user points in the thumbing part of the vertical 
scrollbar, vertical is always true (horizontal thumbing is not currently allowed), flavor 
indicates whether the user has just buttoned down (downClick), is moving the mouse with 
the button down (track), or has just released the button (upClick). Usually, the actual 
scrolling does not take place until the upClick. downClick and track give the client an 
opportunity to display information to the user, such as what page number the current 
cursor location corresponds to (see Cursor.NumberlntoCursor). m and outOfN indicate 
where the cursor is with respect to the entire extent of the thumbing area. For example, if 
m = 200 and outOf N = 400, the user wants to thumb to the middle of the entire object. 
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Note: EnumerateBodiesinlncreasingY and EnumerateBodieslnOecreasingY are quite 
useful when scrolling body windows (see the section on body windows). 

PaintThumbFeedBack: proc[sws: Handle, offset: Percent, portion: Percent 4-0]; 

EraseThumbFeedBack: proc[sws: Handle]; 

GetScrollbar: PROC [sws:Handle, vertical: boolean <- true] returns [window.Handle]; 
Percent: TYPE ■ integer [0.. 100]; 

PaintThumbFeedback, etc. support the painting of feedback into the thumbing region of a 
scrollbar. These items are defined in StarWindowShellExtra3.mesa. 

PercentOf: proc[v: integer, p: Percent] returns [integer]; 

PercentOf expresses p in terms of v. For example, m <- PercentOf lOutOfN, offset] . 
Percentage: proc [part, full: integer] returns [Percent]; 

Percentage returns the percentage of part to full. For example, offset Percentage[m, 
OutOfN]. 

PaintThumbFeedback, etc. support the painting of feedback into the thumbing region of a 
scrollbar. These items are defined in StarWindowShellExtraS.mesa. 

MoreScroilProc: type = procedure [ 
sws: Handle, vertical: boolean, flavor: MoreFlavor, amount: cardinal]; 

MoreFlavor: type » {before, after}; 

A MoreScroilProc is called by the default StarWindowShell scrolling procedures, 
VanillaArrowScroil and VanillaThumbScroll, whenever more body windows are needed to 
continue scrolling. This is used when the client has several body windows butted against 
one another. When the user points at an arrow, VanillaArrowScroil moves all the body 
windows a small amount. When the user point at plus or minus, VanillaArrowScroil moves 
all the body windows by one interior window's height. When the user thumbs, 
VanillaThumbScroll moves all the body windows to an appropriate place based on the 
combined overall height of the body windows. However, the client often does not have the 
entire extent of the object displayed in these body windows but rather wants to tack on 
new body windows on each end as these body windows are scrolled off. This is when the 
client's MoreScroilProc is called, vertical indicates whether the user was scrolling 
vertically or horizontally, flavor indicates whether to tack on more body windows before 
(that is, the user was scrolling down for vertical « true, right for vertical ■ false), or after 
(that is, the user was scrolling up for vertical « true, left for vertical ■ false), amount 
indicates how much extra body window is needed, in screen dots. 

The client's moreScroil procedure is responsible for adding and deleting body windows 
from the shell. The case being handled is that in which the client has a large number of 
pages to display to the user and wishes to manifest only a few. Then we need to handle the 
case in which system scrolling would make a non-manifest page visible, and there is no 
body window for it. Whenever the system is about to perform a scroll function, it checks to 
see if the scroll action would move the visible portion of the bodies off the end of the 



46-19 



46 



StarWindowShell 



existent body windows. If so, it calls a non-nil client MoreScrollProc, indicating how much 
more body window may be displayed. The client may augment the collection of body 
windows or not. The system routines will not scroll past the end of the body windows. The 
client may also use this opportunity to garbage-collect body windows that have been 
scrolled off the other end and are no longer visible. 

noScrollData: ScroilData <~ []; 

noScrollOata indicates no scrollbars at all. 

vaniliaScrollData: ScroilData «- [ 
dispiayHorizontai: false, 
display Vertical: true, 

arrowScroll: nil, actua/Zy VanillaArrowScroll 
thumbScroll: nil,— actua//y VaniilaThumbScroil 
moreScroil: nil]; 

vaniliaScrollData is the default for the scroliData parameter to Create. It indicates 
avertical scrollbar with the StarWindowShell. VanillaXXXScroll procedures described above. 

GetScrollData: procedure [sws: Handle] returns [scroliData: ScroilData]; 

GetScrollData returns the current ScroliData associated with sws. May raise Error 
[notASWS]. 

SetScroilData: procedure [sws: Handle, new: ScroilData] 
RETURNS [old: ScroilData]; 

SetScroilData sets the current ScroliData for sws and returns the previous. May raise 
Error [notASWS]. 

VanillaArrowScroll : ArrowScrollProc; 
VaniiiaThumbScroii: ThumbScrollProc; 

The default scrolling procedures that StarWindowShell provides are exported here. This 
allows a client to insert its own scroll procedures, check for certain conditions that it wants 
to handle, and call StarWindowShell to do the scrolling for other conditions. 

46.2.6 Push, Pop, etc. 

The StarWindowShell returned by Create is not displayed on the screen; that is, is not 
inserted into the visible window tree. A StarWindowShell may be inserted into the 
window tree by calling Push. This is usually not done by the client but rather by some 
other part of ViewPoint, such as the desktop implementation. For example, when the user 
selects an icon and presses OPEN or PROPS, the application (actually the application's 
Containee.GenericProc) creates a StarWindowShell and returns it. The desktop 
implementation then displays the StarWindowShell by doing a Push. 
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A StarWindowShell is removed from the screen by calling Pop. Clients almost never call 
Pop. Rather, StarWindowShell calls Pop when the user selects Close, or PropertySheet 
calls Pop when the user selects Done or Cancel. 

Push allows one shell to be pushed on top of another shell, thus providing the illusion of 
"open-within." For example, Star folders and file drawers use this illusion. 
StarWindowShell has provisions for a shell to display commands in the header of the 
shells pushed on top of it. (See the section one Pushee commands.) Most clients will not 
make use of this feature of Push, because the ContainerWindow interface takes care of 
this for applications that appear as a list of items that may be opened. Fine point: We simplify 

things here by replacing the entire shell. When the shell on top is closed, the shell below still exists umi is simply 
redisplayed. 

Push: PROCEDURE! 

newShell: Handle, topOf Stack: Handler- nil, 
poppedProc: PoppedProc 4~nil]; 

Push displays newShell by inserting it into the visible window tree. If topOfStack is nil, 
newShell is placed directly on the desktop. If topOf Stack is not nil, then newShell is 
pushed on top of topOf Stack and topOf Stack is removed from the display (but see the fine 
point below). If topOfStack is not nil, it must be currently visible ( that is, does not have 
another shell Pushed on top of it). If poppedProc is not nil, it is called when newShell is 
Popped. The poppedProc must either sleep the shell or destroy the shell, usually by 
calling SleepOrOestroy. If poppedProc is nil, newShell will be destroyed when it is 
Popped. Note that Push can be called repeatedly with topOfStack being the newShell from 
the previous call, thus producing a stack of StarWindowShells. May raise Error 
[notASWSl. 

Fine point: For open-within, we are experimenting with opening the newShell overlapping the topOfStack shell, 
allowing the user to look at the container and the thing contained at the sutne time. This has some rathet- complex 
implications with respect to having two views of the same things, being able to open several contained items at 
once, and so forth. 

PushedMe: procedure (pushee: Handle] returns [pusher: Handle]; 

PushedMe returns the next lower shell below pushee in the stack (nil if none). PushedMe 
is defined in StarWindowShellExtra.mesa. 

PushedOnMe: procedure [pusher: Handle] returns [pushee: Handle]; 

This procedure returns the next higher shell above pusher in the stack (NIL if none). 
PushedOnMe is defined in StarWindowShellExtra.mesa. 

PoppedProc: type » procedure [popped, new[Shell: Handle, 
popOrSwap: PopOrSwap pop]; 

PopOrSwap: type ■ {pop, swap}; 

popped is the shell that is being taken out of the visible window tree. newShell is the shell 
that becomes visible because of popped being popped. It is nil if popped was not opened 
within another window. popOrSwap indicates the action that caused the shell to be 
popped, either StarWindowShell.Pop or StarWindowShell.Swap. 
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Pop: PROCEDURE [popee: Handle] returns [Handle]; 

Pop removes popee from a stack of shells and returns the shell that is now on top of the 
stack. If popee was Pushed with a poppedProc, this poppedProc is called. If popee is not 
the top of a stack, then all shells above it in the stack are Popped. May raise Error 
[notASWSj. 

Swap: procedure [ 
new, old: Handle, 
poppedProc: PoppedProc <- nil] ; 

Swap replaces old, which must be the top of a stack, with new. Equivalent to a Pop 
followed by a Push, but with a lot less screen flashing. May raise Error [notASWS]. 

Replace: procedure [new, old: Handle]; 

Replaces the old shell with new without calling old's PoppedProc. old's PoppedProc 

becomes the PoppedProc for new. Fine point: This procedure is currently exported through 
StarWindowSheilExtra. 



46.2.7 Limit and Adjust Procs 

Limit and Adjust procs are client-supplied procedures that allow a client to get control 
whenever a StarWindowShell is going to change size or location. A LimitProc gives the 
client control over the size and placement of a shell. An AdjustProc gives the client an i^Hii 
opportunity to fix up the data structures and display for the shell's body window(s). 

LimitProc: type » procedure [sws: Handle, box: window.Box] returns [window. Box]; 

GetkimitProc: procedure [sws: Handle] returns [LimitProc]; 

SetLimitProc: procedure [sws: Handle, proc: LimitProc] RETURNS [old: LimitProc); 

Whenever the size or location of a shell is going to change, the client's LimitProc is called. 
This allows the client to exercise veto or modification rights over the size and location of a 
StarWindowShell. This is useful, for example, to prohibit a shell from becoming smaller 
than some certain size or from being moved completely ofTthe screen, box is the requested 
size of the shell. The LimitProc should return the desired size of the shell. The LimitProc is 
called before the AdjustProc. The interior box of the shell box returned by the LimitProc is 
passed to the AdjustProc. GetLimitProc and SetLimitProc may raise Error [notASWS]. 

StandardLimitProc: LimitProc; 

A StandardLimitProc is provided that keeps shells on the screen and keeps them from 
getting too small. 

AdjustProc: type s procedure [sws: Handle, box: window.Box, when: When]; 
When: type = {before, after}; 

GetAdjustProc: procedure [sws: Handle] returns [AdjustProc]; 
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SetAdjustProc: procedure [sws: Handle, proc: AdjustProc] RETURNS [old: AdjustProc]; 

The AdjustProc is called whenever the shell is going to change size. It is called both before 
and after the window's size is changed. The box passed to the AdjustProc is the interior 
window's box (the client's viewing region in the shell). The when parameter indicates 
whether the current call is before or after the window's size has been changed. An 
AdjustProc is for those clients whose body window display depends on the size of the 
surrounding shell. For e-xample, if the body window sticks out of the interior of the shell 
and the user must scroll the body window horizontally to see all the contents, then no 
AdjustProc is needed. If, on the other hand, the content of the body window is always kept 
visible regardless of the size of the shell (by wrapping the contents around as in the Tajo 
FiieWindow editor), then the client needs an AdjustProc. GetAdjustProc and 
SetAdjustProc may raise Error [notASWS]. 

46.2.8 Displayed StarWindowShells 

EnumerateOisplayed: procedure [proc: ShellEnumProc] returns [Handle [nil]]; 

EnumerateOisplayedOfType: procedure [ShellType, proc: ShellEnumProc] 
returns [Handle 4-[nil]]; 

EnumerateMyOispiayedParasites: [sws: Handle, proc: ShellEnumProc] 
RETURNS [Handle <~ [nil]]; 

ShellEnumProc: type * procedure [victim: Window.Handle] 

RETURNS [stop: BOOLEAN «- FALSE] 

These procedures enumerate visible StarWindowShells. Each one returns the last shell 
incurred in the enumeration if the ShellEnumProc returns TRUE; otherwise, they return nil. 
EnumerateMyOisplayedParasites may raise Error [notASWS]. 

46.2.9 Errors 

Error: ERROR[code: ErrorCodeJ; 

ErrorCode: type ■ {desktopNotUp, notASWS, notStarStyle,tooMany Windows}; 



46.3 Usage/Examples 

- Create a StarWindowShell 

CreateShell: procedure returns [starwindowSheii.Handle] ■ { 

another: xstring.ReaderBody xstring.FromSTRING["Another"L]; 
repaint: xstring.ReaderBody xstring.FromSTRiNG["Repaint"L]; 
post: xstring.ReaderBody 4-xstring.FromSTRING("Post A Message"L]; 
sampleTool: xstring.ReaderBody <-xstring.FromSTRING["Sampie Tool"L]; 

Create the StarWindowShell 
shell: StarwindowSheii.Handle » starwindowSheii.Create [name: @sampleTool]; 
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— Create a body window inside ttie StarWindowShell 
body: window.Handle • starWindowSheii.CreateBody [ 
sws: shell, 

box: [ [0,0], bodyWindowOims ], 
repaintProc: Redisplay, 
bodyNotifyProc: NotifyProc ]; 

" Create some menu items 

z: UNCOUNTED ZONE 4- StarWindowShell. GetZone [shell]; 

items: array [0..3) of MenuData.ltemHandle *- [ 

MenuData.Createltem [zone: z, name: ©another, proc: MenuProc], 
MenuData.Createltem [zone: z, name: ©repaint, proc: RepaintMenuProc], 
MenuData.Createltem [zone: z, name: @post, proc: Post] ]; 

myMenu: MenuOata.MenuHandle a MenuOata.CreateMenu [ 
zone: z, 
title: NIL, 

array: descriptor [items]]; 
starwindowSheii.SetRegularCommands [sws: shell, commands: myMenu]; 



RETURN [shell]; 



Viewpoint Programmer's Manual 



46.4 Index of Interface Items 



Item 


Pase 


Item 


M. age 


AddPopupMenu.'PROCEOURE 


13 


IsCioseLegai: procedure 


8 


AdjustProc: type 


22 


IsCloseLegalProc: type 


6 


ArrowFiavor: type 


18 


IsCloseLegalProcReturnsFalse: procedure 


8 


ArrowScrollAction: type 


18 


LimitProc: type 


22 


ArrowScrollProc: type 


18 . 


MenuEnumProc: type 


13 


BodyEnumProc: type 


11 


MoreFlavor: type 


19 


Create: procedure 


4 


MoreScroltProc: type 


19 


CreateBody: procedure 


10 


NewStanda rdCI oseE verythi ng : proce du re 


7 


DestallBody: procedure 


12 


noScrotlData: Scroll Data 


20 


Destroy: procedure 


6 


nullHandle: Handle 


6 


Destroy Body: procedure 


10 


PaintThumbFeedBack: procedure 


19 


EnumerateAilMenus: procedure 


13 


Percent:TYPE 


19 


EnumerateBodieslnDecreasingY: procedure 


11 


Percentage: procedure 


19 


EnumerateBodiesinlncreasing Y : procedure 


11 


PercentOf : procedure 


19 


EnumerateDisplayed: procedure 


23 


Pop: procedure 


22 


EnumerateDisplayedOf Ty pe : procedure 


23 


PopOrSwapiTYPE 


21 


EnumerateMyDispiayedParasites: procedure 


23 


PoppedProc: type 


21 


EnumeratePopupMenus: procedure 


13 


Push: PROCEDURE 


21 


EraseThumbFeedBack: procedure 


19 


PushedMe: procedure 


21 


Error: error 


23 


PushedOnMe: procedure 


21 


ErrorCode: type 


23 


Replace: procedure 


22 


GetAdjustProc: procedure 


22 


Scroll Data: type 


17 


GetAvaiiabteBodyWindowDims: procedure 


11 


SetAdjustProc: procedure 


23 


GetBody: procedure 


10 


SetBodyWindowJustFits: procedure 


11 


GetBodyWindowJustFits: procedure 


11 


SetBottomPusheeCommands: procedure 


14 


GetContainee: procedure 


8 


SetContainee 


9 


GetHost: procedure 


8 


SetHost: procedure 


9 


GetlsCioseLegalProc: procedure 


8 


SetlsCloseLegalProc: procedure 


8 


GetLimitProc: procedure 


22 


SetLimitProc: procedure 


22 


GetPreferredDims: procedure 


7 


SetMlddlePusheeCommands: procedure 


14 


GetPreferredPiace: procedure 


7 


SetName: procedure 


9 


GetPusheeCommands: procedure 


14 


SetNamePicture: procedure 


9 


GetReadonly: procedure 


8 


SetPreferredDims: procedure 


7 


GetReguiarCommands: procedure 


13 


SetPreferredlnteriorOims: procedure 


7 


GetScrollBar: procedure 


19 


SetPreferredPlace: procedure 


7 


GetScroliData: procedure 


20 


SetReadOnly: procedure 


9 


GetSleeps: procedure 


16 


SetRegularCommands: procedure 


12 


GetState: procedure 


16 


SetScrollData: procedure 


20 


GetTransitionProc: procedure 


16 


SetSleeps: procedure 


9 


GetType: procedure 


8 


SetState: procedure 


16 


GetZone: procedure 


8 


SetTopPusheeCommands: procedure 


14 


Handle: type 


6 


SetTransitionProc: procedure 


16 


HaveDispiayedParasite: procedure 


9 


ShellEnumProc: type 


23 


InstallBody: procedure 


12 


ShellFromChild: procedure 


11 


IsBodyWindowOutOflnterior: procedure 


11 


ShellType: type 


6 
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Item Page 

SteepOrOestroy: PROCEDURE 16 

StandardCiose: procedure 7 

StandardCloseAll: procedure 7 

StandardCloseEverything: procedure 7 

StandardLimitProc: LimitProc 22 

State: type 16 

SubtractPopupMenu: procedure 13 

Swap: procedure 22 

ThumbFlavor: type 18 

ThumbScrollProc: type 18 

TransitionProc: type 16 

VaniiiaArrowScroll: ArrowScrollProc 20 

vaniilaScroilOata: ScrollData 20 

VaniilaThumbScroil: ThumbScrollProc 20 

When: type 22 
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47.1 Overview 

TIP provides basic user input facilities through a flexible mechanism that translates 
hardware-level actions from the keyboard and mouse into higher-level client action 
requests (result lists). The acronym TIP stands for terminal interface package. This 
interface also provides the client with routines that manage the input focus, the periodic 
notifier, and the STOP key. 

47.1.1 Basic Notification Mechanism 

The basic notification mechanism directs user input to one of many windows in the 
window tree. Each window has a Table and a NotifyProc The tabic is a structure that 
translates a sequence of user actions into a sequence of results that are then passed to the 
notify procedure of the window. 

There are two processes that share the notification responsibilities, the Stimulus process 
and the Notifier process. The Stimulus process is a high-priority process that wakes up 
approximately 50 times a second. When it runs, it makes the cursor follow the mouse and 
watches for keyboard keys going up or down, mouse motion, and mouse buttons going up 
or down, enqueuing these events for the Notifier process. 

The Notifier process dequeues these events, determines which window the event is for, 
and tries to match the events in the window's table. If it finds a match in the table, it calls 
the window's Notify procedure with the results specified in the table. If no match is found, 
it tries the next table in the window's chain of tables. If no match is found in any table, the 
event is discarded. 

The Notifier process is important. To avoid multi-process interference, some operations in 
the system can happen only in the Notifier process. Setting the selection Is one such 
operation. The Notifier process is also the one most closely tied to the user. If an operation 
will take an extended time to complete, it should be forked from the Notifier process to run 
in a separate process so that the Notifier process is free to respond to the user's actions. 
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47.1.2 Tables 

Tables provide a flexible way to translate user actions into higher-level client-defined 
actions. They are essentially large select statements in which the user's actions are 
matched against the left side of a table with a corresponding set of results on the right 
side. Left sides of tables specify triggers—changes in state of keys~and enahlers-eKisting 
state of keys—to be matched with the user actions. Right sides of tables specify results that 
include mouse coordinates, atoms, and strings for keyboard character input. A complete 
syntax and semantics of tables are in §47.3.2 and §47 3.3. 

Tables have a user-editable filed representation that is parsed to build a runtime data 
structure for TIP. The user-editable filed representation must be in the system catalog and 
is assumed to have a file name extension of TIP. When a table is created by calling the 
CreateTable operation, the TIP file is parsed and its runtime data structure is created. In 
addition, a compiled version of the TIP file is created in a file whose name has the 
character c appended to the name of the TIP file. On subsequent calls to CreateTable, this 
TIPC file is used to create the runtime data structure as long as the TIP file has not been 
changed. By avoiding parsing the TIP file, building the runtime data structure from the 
compiled file is much faster. 

The table parser uses a macro package that allows macros to be defined and used in 
writing tables. It is described in §47.3.7. 

Tables may be linked to form a chain of tables. The Notifier process attempts to match 
user actions in the first table of the chain. If no match is found, it tries subsequent tables 
in the chain. If no match is found in any table, the user action i.s di.scarded. Clients can use 
the links of tables to build special processing on top of basic facilities The client can write 
its own table to handle special user actions and, by linking the table to system-defined 
tables, let them handle the normal user actions. An example is in the L' sage/Examples 
section. System-defined tables, which are accessible through the TIPStar interface, are 
described in Appendix A. 

47.1.3 Input Focus 

The input focus is a distinguished window that is the destination of most user actions. 
User actions may be directed either to the window with the cursor or to the input focus. 
Actions such as mouse buttons are typically sent to the window with the cursor. Most 
other actions, such as keystrokes, are usually sent to the current input focus. 

The Notifier process uses either the input focus window or the cursor window to obtain a 
table and a notify procedure. Results from matching the user actions with the table are 
normally passed to the window's Notify procedure. Notify procedures may also be bound 
directly with a table. In this case, results from the table go to the table's notify procedure 
instead of to the window's Notify procedure. 

Clients may make a window be the current input focus and be notified when some other 
window becomes the current input focus. 
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47.1.4 Periodic Notification 

The Notifier process is important because it responds directly to the user. To avoid multi- 
process interference, some operations in the system are restricted to happen only in the 
Notifier process. The periodic notification mechanism allows operations to happen within 
the Notifier process while the user is idle. A periodic notifier is created with a window, 
some results, and a time interval. The window's Notify procedure is called with the results 
every time interval as long as the Notifier process is not processing user actions. 

47.1.5 Call- Back Notification and Setting the Manager 

Call-back notification and setting the manager bypass the normal means of selecting a 
window as the destination of input and allow the client to receive all input. This is useful, 
for example, for mouse tracking when a menu is posted. It must be done only from the 
Notifier process. 

Call-back notification is so named because the client calls back to the Notifier process with 
a special call-back notification procedure, a window, and a table The .Notifier matches 
user actions with the table and sends the results to the call-back .N'otify procedure. It 
continues to do this until the call-back Notify procedure says it is done. User actions that 
are not matched are discarded. 

Setting the manager makes the Notifier process use the manager's table for matching user 
actions and send the results to the manager's Notify procedure. User actions that are not 
matched are discarded. 

While both call-back notification and setting the manager results in all notifications being 
sent to a single place, they are different in the control structure. With call-back 
notification, the client's call stack is not unwound, while setting the manager does not 
take effect until the current notification is processed and its call stack unwound. 

47.1.6 Attention and User Abort 

While most notifications are sent to Notify procedures from the Notifier process, a 
mechanism allows asynchronous notification of the stop key. An AttentionProc may be set 
for a window that is called whenever the STOP key is depressed in that window. It is called 
from outside the Notifier process as soon as the stimulus level sees the key go down. For 
those windows that do not set an AttentionProc, the system keeps a user abort flag that 
records whether the stop key was depressed. Clients may call UserAbort to check if the 
fiag is set. It is cleared when any notification is sent to the window's Notify procedure. 

47.1.7 Stuffing Input into a Window 

TIP provides operations that allow a client program to call the Notify procedure of a 
window with results that the client constructs. StuffResults allows a client to pass an 
arbitrary results list to a window. StuffString, StuffSTRiNG, and Stuff Character allow 
strings and characters to be passed to a window. 
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47.2 Interface Items 

47.2.1 Results 

Results: TYPE ■ long pointer to ResultObject; 

ResuitObject: type • record [ 
next: Results, 
body: select type: *from 

atom ■ > [a: ATOM], 

bufferedChar « > null, 

coords ■ > [place: window.Place], 

int M>[\: long integer], 

key ■ > [key: KeyName, downUp: OownUp], 

nop ■ > [1, 

string ■ > [rb: xstring.ReaderBody], 
time a > [time: System.Pulses], 
enocase]; 

ATOM: TYPE ■ Atom.ATOM; 

DownUp: type ■ LeveliVKeys.OownUp; - {down, up} 

Key Name: type « LeveiivKeys.KeyName; jmn^ 

The right side of a statement in a table is a list of results to be passed to the Notify 
procedure when there is a match on the left side. Each element of this list of results is 
described by a ResuitObject. The atom variant contains the atom from the table's right 
side. The place in the coords variant is relative to the window receiving the results. The 
reader body of the string variant is either from the bufferedChar results or from a string 
constant in the table. The pulses of the time variant is the value of System. GetPulses at 
the time the event actually occurred. 

Character input is buffered by the Notifier process. If the result of a match is a 
bufferedChar, the Notifier process buffers the character and tries to match the next user 
actions. If there are no more user actions and the buffer of character input is not empty, 
the Notifier process calls the Notify procedure with the buffered character input. If the 
next action produces a result that is not another character input, the Notifier process calls 
the Notify procedure with the buffered character input and then calls it with the new 
result. If the Notifier process gets behind the user and a lot of character input actions are 
queued, it collects them and passes them together to the client instead of one at at time. 

KeyName is an enumerated that describes the keyboard and mouse buttons. See §5.2 in 
the Pilot Programmer's Manual (610E00160) for a complete list of the elements. 

47.2.2 Notify Procedure 

NotifyProc: type ■ procedure Iwindow: window.Handle, results: Results]; jHII 

A NotifyProc is the means of notifying a window of user input. The parameters are the 
window that is receiving the input and the list of results that describe the input. 
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Normally, the results are from the TIP table associated with the window. Notify 
procedures may also be bound directly with a table. In this case, results from the table go 
to the table's Notify procedure instead of to the window's Notify procedure. 

47.2.3 TIP Tables 

Table: type ■ long pointer to TableObject; 
TableObject: type; 

Table is a pointer to the internal representation of a table 
GetTableLink: procedure [from: Table] returns [to: Table]; 
SetTableLink: procedure [from, to: Table] returns [old: Table]; 

GetTableLink and SetTableLink allow the tables to be linked. GetTableLink returns the 
table following from in the chain, returning nil if there is no successor table. SetTableLink 
sets the link of table from to to and returns the old value. 

SetTableOpacity: procedure [table: Table, opaque: boolean] 
returns [oldOpaque: boolean]; 

GetTableOpacity: procedure [table: Table] returns [boolean]; 

SetTableOpacity .set.s the opacity of table and returns the old value,, while 
GetTableOpacity returns its value. If a table is opaque, unrecognized user actions are 
discarded without searching the table chain past the opaque entry. 

47.2.4 Associating Notify Procedures, Tables, and Windows 

SetTableAndNotifyProc: procedure [ 

window: window.Handle, table: Table <- nil, notify: NotifyProc «- nil]; 

SetTableAndNotifyProc makes window a TIP client and associates the table and Notify 
procedure with the window. If window is already a TIP client and table or notify is nil, 
then the old value is retained. 

SetTable: procedure [window: window.Handle, table: Table] returns [oldTable: Table]; 
GetTable: procedure [window: window. Handle] returns [Table]; 

SetTable sets the table associated with window to be table and returns the old table. 
GetTable returns the table associated with window. 

SetNotifyProc: procedure [window: window.Handle, notify: NotifyProc] 
RETURNS [oidNotify: NotifyProc]; 

GetNotifyProc: procedure [window: window.Handie] returns [NotifyProc]; 
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SetNotifyProc sets the Notify procedure associated with window to be notify and returns 
the old Notify procedure. GetNotifyProc returns the Notify procedure associated with 
window. 

SetNotifyProcForTable: procedure [table: Table, notify: NotifyProc] 
RETURNS [oldNotify: NotifyProc]; 

GetNotifyProcFromTable: procedure [table: Table] returns [NotifyProc]; 

SetNotifyProcForTable binds the Notify procedure, notify, with table and returns the old 
value of bound Notify procedure. Results from matches within the table go to notify 
instead of to the Notify procedure for the window this table is associated with. 
GetNotifyProcFromTable returns the Notify procedure bound to table. 



47.2.5 Creating and Destroying Tables 

CreateTable: procedure [ 

file: xstring.Reader, z: uncounted zone <- nil, contents: xstring.Reader nil] 
RETURNS [table: Table]; 

CreateTable generates a TIP table from the text file named by file (which may not be nil). 
file is expected to be in the system file catalog. Storage for the table is allocated in z or 
from the implementation's zone if z is nil. contents is the default contents of file; it is used 
if (1) the 'I boot switch is set, (2) the file cannot be read, or (3) the signal InvaltdTable is 
resumed. (See InvalidTable for further details of how to treat that signal.) 

When file is parsed, a compiled form of the table is written into a file with a name 

constructed by appending a C on the end of file. Fine point: file .shoujd typically tiave the extension 

.TIP. When CreateTable is called, if a .TIPC file exists that was created from file, the TIPC 
file is used to generate table. If the *0 boot switch is set, CreateTable does not look for a 
TIP file: it looks directly for a TIPC file. May raise the signal InvalidTable. 

CreateCharTable: procedure [ 

z: UNCOUNTED zone 4- NIL, buffered: boolean <~ true] returns [table: Table]; 

CreateCharTable creates a TIP table such that any down transition of any of the 
keystations (not key tops) in the main typing array have a right-hand side of bufferedchar. 
Storage is allocated from z if it is non-NiL or from the TIP implementation's zone. The 
boolean buffered is ignored and will be removed when this interface is updated. 

CreatePlaceHoiderTable: procedure [z: uncounted zone nil] returns [table: Table]; 

CreatePlaceHolderTable creates a placeholder TIP table. Pla'ceholder tables contain no 
information themselves but allow other tables with information to be linked to them. 
Storage is allocated from z if it is non-NiLor from the TIP implementation's private zone. 

DestroyTable: procedure [long pointer to Table]; 

Destroy Table frees the table addressed by the parameter and then sets the table to nil. 
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47.2.6 Input Focus 

SetlnputFocus: proc[ 

w: window.Handle, takeslnput: boolean, newlnputFocus: LosingFocusProc<-Niu 
dientData: long pointer*- nil]; 

SetlnputFocus makes the window w the input focus. If w allows type-in, takeslnput should 
be set to true; otherwise, takeslnput should be set to false. newlnputFocus is called when 
w loses the input focus. It is passed cllentOata as the value of its long pointer parameter. 
If w ■ nil, the input focus is cleared, that is, input focus notifications are sent to the 
backstop! n put Focus (see below). 

LosingFocusProc: type « procedure [w: Window.Handle,data: long pointer]; 

LosingFocusProc describes the procedure type that is used to let the input focus know it is 
no longer the input focus, w is the Window.Handle of the window that was the input focus, 
and data is the client data passed to SetlnputFocus. 

GetlnputFocus: proc returns [window.Handle]; 

GetlnputFocus returns the window that currently has the input focus. 
backStoplnputFocus: readonly window.Handle; 

The window backStoplnputFocus gets all input focus notification when no other window 
requests to be the input focus. It may be NIL. 

SetBackStoplnputFocus: procedure [window: window.Handle]; 

SetBackStoplnputFocus sets backStoplnputFocus, the window that gets all input focus 
notification if no other window requests to be the input focus. 

FocusTakeslnput: proc returns [boolean]; 

FocusTakeslnput returns true if the current input focus accepts input, false otherwise. 
ClearlnputFocusOnMatch: proc [w: window.Handle]; 

CiearlnputFocusOnMatch is used to clear the input focus in a window that has the input 
focus. This procedure is usually called by clients that are implementing their own window 
type when they are destroying a window. 

47.2.7 Character Translation 

CharTranslator: type « record [ 

proc: KeyloCharProc, data: long pointer]; 

KeyToCharProc: type ■ procedure [ 

keys: long pointer to KeyBits, key: KeyName, downUp: OownUp, data: long pointer, 
buff er: xstring. Writer] ; 

A CharTranslator is used to construct characters from the state of the keyboard when a 
buffereochar result is encountered. The KeyToCharProc is called when the Notifier needs 
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to construct a character from the state of the keyboard, keys describes the current state of 
the keyboard, key and downUp describe the current character transition. The procedure 
should append the corresponding character(s) to buffer. There is a CharTranslator for each 
table. 

KeyBits: type ■ LeveiivKeys.KeyBits; 

SetCharTranslator: procedure [table: Table, new: CharTranslator] 
RETURNS [old: CharTranslator] ; 

GetCharTranslator: proc [table: Table] returns [o: CharTranslator]; 

SetCharTranslator sets the character translator for table, returning the old value. 
GetCharTranslator returns the character translator for table. 

47.2.8 Periodic Notification 

PerlodicNotify: type [1]; 
nullPeriodlcNotify: PerlodicNotify; 

PerlodicNotify is a handle for a periodic notifier. Periodic notiflers are a means of 
notifying windows at regular intervals from within the Notifier. nullPeriodlcNotify is the 
null value for PerlodicNotify. 

CreatePeriodicNotify: proc [ 

window: window.Handie, results: Results, milliseconds: cardinal, 
notifyProc: NotifyProc«-NiL] 
returns [PerlodicNotify]; 

CreatePeriodicNotify registers a periodic notification. If notifyProc « nil, the notify 
procedure associated with window is used. If notifyProc # nil is called: this is useful if the 
client is running in a background process but wants to perform some operation that must 
be done in the Notifier process, such as obtaining the current selection. If there is a COORDS 
result and window ■ nil , that result is [0, 0|. If notifyProc » nil and window « nil , the 
Error[other] is raised. The specified Notify procedure is called with parameters window 
and results once every milliseconds milliseconds as long as no user action notifications are 
taking place. If milliseconds = 0, it runs once and then destroys itself. The resulting list 
should not contain any entries of type nop or bufferredChar Right-hand sides of type 
coords are adjusted to refiect the actual mouse position relative to the window being 
notified. The results list will not be copied. Its allocation is up to the client. 

CancelPeriodicNotify: proc [ 

PerlodicNotify] returns [null: PerlodicNotify]; 

CancelPeriodicNotify stops the periodic notification passed in by removing the notification 
from the list of registered procedures and returns nullPeriodicNotify. This procedure 
raises Error[noSuchPeriodicNotifier] if the handle passed in is not valid (calling it with 
nullPeriodlcNotify has no effect). 

47.2.9 Call-Back NotiHcation 

CallBack: procedure [window: window.Handle, table: Table, notify: CallBackNotifyProc]; 
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CailBackNotifyProc: type > procedure [window: window.Handie, results: Results] 
RETURNS [done: boolean]; 

Call-back notification allows the client to receive all input. For example, it is useful for 
mouse tracking when a menu is posted. CallBack uses table to match all user input and 
calls notify for each successful match in the table with window and the results from the 
table as parameters. CallBack continues to send ail notifications to notify as long as notify 
returns done: false. Call-back notification is similar to setting the Manager except that 
the client's call stack is not unwound. User actions that are not matched are discarded. 

47.2.10 Manager 

Manager: type ■ record [ 

table: Table, window: window.Handle, notify: NotifyProc]; 

nullManager: Manager « [nil. trash, trash]; 

Manager sends all user actions through table and notify, using window instead of 
through the window, table, and Notify procedure determined by actionToWindow and 
TIPs Match process. If table is nil, as in nullManager, then the standard mechanisms are 
used to determine where actions are sent. 

GetManager: proc returns [current: Manager]; 

GetManager returns the current manager. 

ClearManager: procedure « inline . . .; 

ClearManager sets the manager to nullManager. It should only be called by clients who 
know that they set the manager from null to non-null. 

SetManager: procedure [new: Manager] returns [old: Manager]; 

SetManager does the obvious thing. 

47.2.11 User Abort 

UserAbort: proc [window.Handle] returns [boolean]; 

UserAbort returns whether the user abort flag is set for the window. The bit may be set by 
calling SetUserAbort or by the system if the window does not have an attention procedure 
and the stop key is depressed in that window. If window is nil, the Userlnput package 
checks to see whether the user has done a global abort. When a non-shift key goes down, 
this flag and the global abort flag are cleared. 

ResetUserAbort: proc Iwindow. Handle]; 

ResetUserAbort sets the user abort flag for the window to false. 
SetUserAbort: proc [window.Handle] 
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SetUserAbort sets the user abort flag for the window. It does not call the window's 
attention procedure, if there is one. 



47.2.12 Attention 

AttentionProc: TYPE = proc [window: window.Handie]: 

An AttentionProc is a procedure called whenever the stop key is depressed. It is called 
from a high-priority process— not the Notifier— as soon as the stimulus level sees the key 
go down. 

SetAttention: proc [ window.Handie, attention: AttentionProc] 

SetAttention sets the attention procedure for the window. The procedure attention is 
called asynchronously whenever the STOP key is depressed. 

47.2.13 Stuffing Input into a Window 

Stuff Character: proc [ 

window: window.Handie, char: xstring.Character] returns [boolean] 

StuffCharacter allows a client to drive the type-in mechanism as though a character were 
coming from the. user. The Notify procedure of window is called with a string result that 
contains char. The returned boolean is true only if window was prepared to accept input. 

Stuff CurrentSelection: proc [window: window.Handie] returns [boolean] 

StuffCurrentSelection allows a client to drive the type-in mechanism as though the 
contents of the current selection were coming from the user. The selection is converted to a 
string, and the string is passed to the window's Notify procedure. (See the Selection 
interface for a description of the current selection.) The returned boolean is TRUE only if 
window was prepared to accept input. 

StuffResults: procedure [window: window.Handie, results: Results]; 
Stuff Results calls the notify proc of window with results. 

StuffString: proc [window: window.Handie, string: xstring.Reader] returns [boolean] 

StuffString allows a client to drive the type-in mechanism as though string were coming 
from the user. The Notify procedure of window is called with a string result that contains 
string f . The returned boolean is true only if window was prepared to accept input. 

StuffSTRiNG: procedure [window: window.Handie, string: long string] 
returns [boolean]; 

StuffSTRiNG calls the Notify procedure of window with a results list that contains a string 
ResultObject whose reader body describes the characters in string. 

StuffTrashBin: proc [window: window.Handie] returns [boolean] 

StuffTrashBin is currently not implemented. 
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47.2.14 Errors 

InvaiidTable: signal [type: TableError, message: xstring.Reacler]; 
TableError: type • {fileNotFound, badSyntax};. 

InvaiidTable is only raised by CreateTable. The type is fUeNotFound if the file could not be 
found and the message string was empty. fiieNotFound is raised as an error . The type is 
badSyntax if the current file is syntactically incorrect. If badSyntax is RESUMEd and 
message is not empty, the message is written into file, and it is reparsed. If the file has 
been overwritten, or message is empty, and there is a syntax error, the error is badSyntax. 
In this case if the signal is resumed, CreateTable simply returns nil. 

Error: error [code: ErrorCode]; 

ErrorCode: type ■ {noSuchPeriodicNotifier, other}; 

ReturnToNotifier: error [string: xstring.Reader]; 

Sometimes a client is deep in the call staclc of some Notifier-invoked operation from which 
it wishes to unwind. The ERROR ReturnToNotifler can be raised and will be caught at the 
top level of the Notifier process. Clients can catch this error, post a message with string in 
it, and let the error propagate up. 

47.2.15 Miscellaneous Items 

GetPiace: procedure [window: window.Handle] returns [window.Place]; 

GetPiace returns the window relative coordinate of the last user action that was matched. 
GetPiace should only be invoked while in the Notifier process. 

actionToWindow: packed array KeyName of boolean; 

actionToWindow determines if a user action should be sent to the window containing the 
cursor (true) or to the window containing the current input focus (false). This array is 
global to the entire environment. It is initialized to have all actions go to the input focus, 
except those associated with the Adjust, Menu, and Point mouse buttons and the STOP key. 

caretRate: Process.Ticks; 

cllckTlmeout: System.Pulses; 

clickTimeout and caretRate are values that are set by user profile. Clients that implement 
blinking carets may use caretRate to determing the rate of caret blinking. Clients that 
implement click timeout without using the timing facilities in tables may use 
clickTimeout to determine the maximum time allowed between two clicks of a multi-click. 

FlushUserlnput: procedure; 

FlushUserlnput empties the queue of pending user actions (type-ahead and button-ahead). 
GetNotifierProcess: procedure returns [process] ; 
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GetNotifierProcess returns the current Notifier process. It is defined in TIPXX.mesa. 

47.2.16 "Look- Ahead** 

TIP allows a client to "look ahead" at the next results that TIP will deliver and choose to 
process them or not. This allows the client to implement possible performance gains. For 
example, say the client's NotifyProc is called with a string result (the user typed some 
characters) and suppose there is some significant setup processing the client must do to 
get to the point where the characters can actually be inserted and displayed. If the next 
thing in the input queue is more characters, the client can save that setup processing time 
by looking at what iss next in the input queue before returning from the NotifyProc and 
continuing to process characters until the next item in the queue is not a string result. 

GetResults: procedure [window: window.Handle, resuitsWanted: ResultsWanted <- nil] 
RETURNS [results: Results]; 

ResuitsWanted: type ■ procedure [ 

window: window.Handle, table: Table 4-nil, results: Results] 
returns [wanted: boolean]; 

GetResults calls resuitsWanted and if resuitsWanted returns true, then GetResults 
returns the results that would next go to window's NotifyProc and removes from the input 
queue the event that produced results. If resuitsWanted returns false, the event is left in 
the input queue and processed "normally." When resuitsWanted is called, results is the 
next results, and window is the window that those results would go to. If table is not nil, 
then the results go to the table's NotifyProc. These items are defined in TIPX. mesa. 

47.3 Usage/Examples 

47.3.1 Periodic Notification 

The following example shows the use of a periodic notifier for updating a display of the 
volume page count. The page count is updated every 20 seconds, provided that the Notifier 
is not otherwise occupied. 

window: window.Handle 4- ...; 

updateCount: Atom.ATOM <-Atom.MakeAtom["UpdateCount"L]; 
results: ResultsObject «~ [next: nil, body: atom[a: updateCount]]; 
pageNotif ler: PeriodicNotify <- 

CreatePeriodicNotifty[window: window, results: ©results, milliseconds: 20000]; 

MyNotifyProc: NotifyProc » { 
input: Results; 

FOR input results, results.next do 
WITH z: input select from 
atom ■ > 

IF z.a ■ updateCount then { 

- Code to update page count on screen;} 
else ( 

— Code to handle other atoms}: 
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endcase; 
ENDLOOP}; 

47.3.2 Syntax of TIP tables 



Following is the BNF description for the syntax of tables. Non-terminals are boldface, and 
terminals are non-bold Titan (such as Fas tMouse). The characters " . ", " ; 

"=>»', and "}" in the BNF below are terminal symbols. The semantics are 
described in the next section. 



TIPTable 



Options 

OptionList 

Option 

SmallOrFast 

FastOrSlowMouse 

Expression 
Statement 

TriggerStmt 
EnableStmt 

TriggerChoiceSeries 



EnabieChoiceSeries 



TriggerChoice 
EnableChoice 
FinaiChoice 

TriggerTerm 
EnableTerm 

TimeOut 

KeyEnableList 

Key 

Results 

Resuititems 
Resuitltem 



:: ■ Options TriggerStmt . 

Itotes tables texminate with a period. 

■ empty I OPTIONS OptionList ; 
I Option I Option , OptionList 
I SmailOrFast | FastOrSlowMouse 
I Small I Fast 

■ FastMousej SlowMouse 

■ AND TriggerChoice j WHILE EnableChoice | => Statement 
I TriggerStmt | EnableStmt | Results 

« SELECT TRIGGER FROM TriggerChoiceSeries 
I SELECT ENABLE FROM EnabieChoiceSeries 

I TriggerChoice ; TriggerChoiceSeries 
i TriggerChoice ENDCASE FinaiChoice 
I ENDCASE FinaiChoice 
I EnableChoice ; EnabieChoiceSeries 
I EnableChoice ENDCASE FinaiChoice 
1 ENDCASE FinaiChoice 

I TriggerTerm Expression 
I EnableTerm Expression 
I empty | => Statement 

:: • ( Key I MOUSE | ENTER | EXIT ) TimeOut 
:: ■ KeyEnableList I Predicateident 

:: ■ empty | BEFORE Number | AFTER Number 

:: M Key I Key I KeyEnableList 

Note: the \ between Key and KeyEnableList is a 
terminal and must be entered. 
:: a Keyident Up | Keyident Down 

:: ■ Resuitltem I Resuitltem , Results | Resuitltem Expression 

( { Resuititems } 
: : m Resuitltem | Resuitltem Resuititems 
:: 3 COORDS | BUFFEREDCHAR | CHAR | KEY | TIME 

I Number] String | Resultldent 
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String 



"any sequence of characters not containing a 



Resuitldent 

Keyident 

Predicateldent 



Ident 
(dent 
Ident 



47.3.3 Semantics of Tables 



The whole match process can be viewed as a SELECT statement that is continuously reading 
key transitions, mouse movements, or key states from the input queue. A trigger 
statement has the effect of looking at the next action recorded in the input queue and 
branching to the appropriate choice. An enable statement implies selection between the 
different choices according to the current state of the keyboard or the mouse keys. Trigger 
terms may appear in sequence, separated by and. They might be mixed with enable terms, 
which in turn are characterized by the keyword while. A timeout following a trigger 
indicates a timing condition that has to hold between this trigger and its predecessor. The 
number associated with the timeout, expresses a time interval in milliseconds. Events 
starting with the same sequence of trigger, enable terms, or both, are expressed as nested 
statements. Result items may be Identifiers, numbers, strings, or the keywords COORDS, 
BUFFEREDCHAR, CHAR, KEY, or TIME. The results of a successfully parsed event are 
passed to the client. Numbers are passed as LONG integers, and strings as 
xstring.ReaderBodys. BUFFEREDCHAR and CHAR come as xstring.ReaderBodys 
containing the character interpretation of the key involved with the event as defined by 
the CharTranslator. COORDS results in a window. Place containing the mouse coordinates 
of the event. 



Option 
SmaiiOrFast 



:: a SmaiiOrFast I FastOrSlowMouse 

:: ■ Small I Fast 

TIP can produce its internal table in two formats: one designed 
for compactness (default) and one for speedy execution. This 
option indicates which format should be used. 



FastOrSlowMouse 



FastMouse I SlowMouse 



FastMouse 
SlowMouse 



The TrIggerTerm MOUSE means all mouse movement. 

The TriggerTerm MOUSE means only the most recent mouse 

motion (default). 



Expression 

AND TriggerChoice 



:: a AND TriggerChoice | WHILE EnableChoice | => Statement 

match if and only if TriggerChoice is the next input event after 
the preceding choice. For example, A Down AND B Down 
means A goes down and then B goes down (with no intervening 
actions like A Up or mouse motion). 



WHILE EnableChoice match if EnableChoice is also true at this point. For example, A 

Down WHILE B Down matches if A goes down while B is 
down. 
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=> Statement 

Statement 

TriggerStmt 

EnabieStmt 

EnableStmt 

TriggerStmt 

TriggerTerm 

Key 

MOUSE 

ENTER 
EXIT 

TimeOut 

BEFORE Number 



AFTER Number 



EnableTerm 

KeyEnabieList 

Key 

Key 

Keyldent 



continue processing at Statement (it is used for results and 
common prefixes). 

• TriggerStmt | EnableStmt | Results 

m SELECT TRIGGER FROM TriggerChoiceSeries 

■ SELECT ENABLE FROM EnableChoice Series 

matches if any of the EnableChoiceSeries have already 
happened. 

matches if any of the TriggerChoiceSeries have just happened. 

:: - ( Key I MOUSE | ENTER | EXIT ) TimeOut 

matches if the appropriate key transition occurs. 

matches if there is mouse motion (useful for tracking the 

mouse). 

matches if the mouse enters the window, 
matches if the mouse leaves the window. 

:: ■ empty | BEFORE Number | AFTER Number 

matches if the associated TriggerTerm happens within a number 
ofmilliseconds of the preceding (matched) user action. For 
example, A Down AND B Down BEFORE 200 would 
match if A went down and then B went down within 1/5 second 
(and if there were no intervening actions). 

matches if the associated TriggerTerm happens a number of 
milliseconds or more after the preceding user action. For 
example, A Down AND B Down AFTER 200 would 
match if A went down and then B went down more than 1/5 
second later (and if there were no intervening actions). 

:: ■ KeyEnabieList I Predicateident 

is true if any of the Keys are true. 
:: » Keyident UP | Keyldent DOWN 



is true if the appropriate transition has happened (if this is part 
of a trigger term, it is the current user action; if this is an enable 
term, it has already happened). 

identifies the keyboard key. The identifiers should be one of: A 
... Z, One, Two, Three, ... Zero, Adjust, AGAIN, OpenQuote, 
DEFAULTS, BackSlash, BS, SUBSCRIPT, SMALLER, Comma, 
KEYBOARD, TAB, PROPS, COPY, Minus, DELETE, 
MARGINS, Equal, EXPAND, FIND, HELP, ITALICS, 
UNDERLINE, Keysetl, Keyset2, Keysets, Keyset4, Keysets, 
LeftBracket, LeftShift, LOCK, MouseMiddle, CENTER, MOVE, 
NEXT, SAME, Period, Point, CloseQuote, SUPERSCRIPT. 
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Resultltem 

String 
Resuitldent 

COORDS 

BUFFEREDCHAR 



CHAR 
KEY 



TIME 

String 

Number 

Resuitldent 



RETURN, RightBracket, RightShift, BOLD, SemiColon, Slash, 
Space, OPEN, PARATAB, UNDO, STOP, A8, A9, AlO, Al I, 
A12, LI, L4, L7, LIO, Key47, R3, R4, R9, RIO 

Note: There are no names for shifted characters like left or right 
paren. Instead, specify one or both shift keys plus the unshifted 
key name. For example, Nine Down WHILE LeftShift Down 
instead of LeftPar en Down. 

Seethe LevellVKeys chapter and the Pi/o^ Programmer's 
Manual for (610E00160) for more information on the keyboard. 

:: . COORDS | BUFFEREDCHAR | CHAR | KEY | TIME 

j String | Number | Resuitldent 
:: ■ "any sequence of characters not containing a " " 
:: ■ Ident 

returns a coord ResultElement with the coords of the last user 
action. 

returns a string ResultElement containing the character 
representations of the last user actions that were also buffered 
characters. 

same as BUFFEREDCHAR 

returns a key ResultElement with the current state of the key 

(not recommended in normal usage. Usually, a more complex 

TIP table is indicated if you are using this result). 

returns a time ResultElement with the time of the last 

(matched) user action. 

returns a string ResultElement. 

returns an integer ResultElement. 

returns an atom ResultElement. 



Predicateldent 
Predicateident 



Ident 



A predicate is an atom that can have a procedure associated 
with it (defined in SpecialTIPX.mesa). This procedure returns a 
BOOLEAN. It is called by TIP when a predicate atom is 
encountered in a TIP table. Several useful predicates are 
provided by ViewPoint to distinguish physical keyboards: 
••aLevel4", "eLevel4", "jLevel4", "aLevelS", "eLevelS", "jLevelS" 
(where a = American, e = European, j = Japanese, Level4 = 
8010, Levels = 6085). For example, adding this to a TIP table: 
TAB Down => SELECT ENABLE FROM 

eLevelV => SomethingSpecial 

ENDCASE; 

would result in "SomethingSpecial" being passed in the results 
list if and only if the TAB key went down on a European 6085 
keyboard. See NormalKeyboard.TIP in Appendix A for more 
examples. 
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47.3.4 Example Table 

SELECT TRIGGER FROM 
Point Down »> 

SELECT TRIGGER FROM 

Point Up BEFORE 200 AND Point Down BEFORE 200 «> 
SELECT ENABLE FROM 

Le£tShift Down «> COORDS, Shi£tedDoubleClick 
ENDCASE *> COORDS f NormalDoubleClick; 

Adjust Down BEFORE 300 «> PointAndAd just ; 
ENDCASE >> COORDS, SimpleClick; 



This table produces the result element (atom) NormalDoubleClick along with the 
mouse coordinates if the left mouse button goes down, remains there not longer than 
200 ms, and goes down again before another 200-ms elapse. The result is 
Shif tedDoubleClick if the same actions occur but the left shift key is also down. If 
the right mouse button goes down less than 300 ms after the initial Point Down and 
the left mouse button also goes down, PointAndAd jus t results. Finally, the table 
specifies the result SimpleClick (with coordinates) if Point goes down but none of the 
above-described succeeding actions occurs. 

47.3.5 Simple TIP Client Example 

This example shows a simple TIP client. The window acts in the followingway. If the left 
(Point) mouse button is depressed, the window becomes the input focus and the cursor 
changes to its special shape. As long as the window is the input focus and the cursor is 
in the window, it remains the special shape but returns to the original shape when the 
mouse leaves the window. Text is displayed in the place in the window where the 
depressed left (Point) mouse button is released. 

The procedure InitAtoms is part of the initialization code. It creates the four atoms that 
the Notify procedure understands. It is put in a separate procedure so the string literals 
will not be allocated in the global frame. The procedure InitWindow initializes the 
window by attaching the context data and setting the table and Notify procedure. 

This example uses the system's table from TIPStar. The fragments of the 
NormalMouse.tip portion of TIPStar's normal table that are used to generate the atom 
results in this example are 

Point Down -> SELECT ENABLE FROM 

[SHIFT] TIME, COORDS, Shift, PointDown; 
ENDCASE -> TIME, COORDS, PointDown; 

Point Up *> SELECT ENABLE FROM 

[SHIFT] => TIME, COORDS, Shift, PointUp; 
ENDCASE »> TIME, COORDS, PointUp; 

ENTER = > Enter; 
EXIT = > Exit; 

The Notify procedure TIPMe looks at the results and understands four atoms and string 
input. For the atom pointDown, if the window is not already the input focus, it sets the 
window as the input focus and sets the cursor to its special shape. For the atom pointUp, 
it saves the place the event occurred as ,the location to display text. The enter atom 
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fiddles with the cursor if the window is the input focus. The exit atom restores the 
cursor. If the window is the input focus and the user types into the window, a string 
result is sent to the Notify procedure containing the characters typed. The 
NormalKeyboard.tip portion of TIPStar's normal table contains the bufferedchar results 
for the keyboard-keys-going down events. 

Handle: type • long pointer to Object; 
Object: type ■ . . .; 

contextlype: Context.Type « Context.UniqueTypen; 
pointDown, pointUp, enter, exit: Atom.ATOM; 

InitAtoms: procedure ■ { 

pointDown *- Atom.MakeAtom("PointDown"L]; 
pointUp 4- Atom.MakeAtom("PointUp"L]; 
enter Atom.MakeAtom[''Enter"L]; 
exit 4- Atom.MakeAtom["Exit''L]}; 

InitWindow: procedure [window: window.Handle] ■ { 
h: Handle « zone.NEw[Object *- []]; 

Context.Create[type: contextlype, data: h, proc: OestroyContext, window: window]; 
TiP.SetTableAndNotifyProcC 

window: window, table: TiPStar.NormaiTableH, notify: TIPMe]}; 

TlPMe: Tip.NotifyProc » { 

h: Handle a Context.Find[type: contextType, window: window]; 
place: window.Place; , 

FOR input: TiP.Results «— results, input.next until input = nil oo 
WITH z: input select from 
coords ■ > place <- z.piace; 
atom ■ > select z.a from 
pointDown ■ > 

if -^h.haslnputFocus then { 
TiP.SetlnputFocus[ 

window: window, takeslnput: true, 
newlnputFocus: MyLosingFocusProc, clientOata: hj; 
SaveCursorAndSetMine[h]} 
pointUp ■ > h.textPlace 4- place; 

enter a > iFh.haslnputFocusTHENSaveCursorAndSetMinefh]; 
exit ■ > RestoreCursor[h]; 
endcase; 
string ■ > 

h.textPlace <- DisplayTextAtPlace[h: h, reader: @z.rb, place: h.textPlace]; 
endcase; 
endloop}; 

MyLosingFocusProc: TiP.LosingFocusProc ■ { 
OPEN h: NARROw[clientOata, Handle]; 
h.haslnputFocus <- false}; 
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47.3.6 Modifying an Existing TIP Client 

This example shows how an existing TIP client may be modified. Assuming the 
existence of a text window package similiar to that in Tajo, this example builds a TTY- 
like window on top of it. It modifies the text window's behavior in two ways. First, it 
changes the table that the text window uses by linking its own table on the front of the 
normal table that the text window package uses. It also has its own Notify procedure 
that looks for the STOP key going down but passes all other notifications to the text 
window's Notify procedure, which it saves. 

This example writes its own table. The table maps shift backspace to the character 
Control-W, backspace to the character Control-H, the DELETE key to the DEL character 
and the TAB key to the ESCAPE character. This table handles only a few of the 
functions; it is linked onto TIPStar's normal table to provide the bulk of the functions. 

— File: TTY.tip 

[DEF SHIFT, (Le£tShift Down I RightShift Down | Key47 Down | A12 Down)] 

SELECT TRIGGER FROM 

BS Down >> SELECT ENABLE FROM 
[SHIFT] «> '•\027"; 
ENDCASE "VOIO"; 

DELETE Down «> ••\177"; 

TAB Down a> ''\03,3'*; 

ENDCASE. 

Handle: type ■ long pointer to Object; 
Object: type ■ . . .; 

contextType: Context-Type ■ Context.UniqueTypef]; 
stop: Atom.ATOM; 

Init: PROCEDURE ■ { 

rb: XString.ReaderBody ^XStrlng.FromSTmNGtTrY.tip 'L]; 
stop4- Atoin.MakeAtom["Stop"Ll; 
myTable <-TIP.CreateTable{file: @rbl; 

n ^ TIP.SetTableLink[f rom: myTable, to: TIPStar.NormalTable[]}; 

Create: procedure [window: window.Handle, ...]■{ 
h: Handle • zone.NEw[Object []]; 
TextWindow.Create[window, . . .]; 

h.oldNotify TiP.SetNotifyProc[window: window, notify: TIPMe]}; 

TIPMe: TiP.NotifyProc > { 

h: Handle ■ Context.Find[type: contextType, window: window]; 
WITH z: results select from 
atom a > select z.a from 
stop ■ > { 

TiP.FIushUserlnputn; 

SendHaltNotification[h]; 

return}; 
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enocase; 

h.oidNotifyfwindow, results]}; - normally pass results to text window's notify 



47.3.7 Macro Package 



The macro package used in TIP is based on the general-purpose macrogenerator 
described by Strachey in Computer Journal (October 1965). The following summary is 
based on that article; see the article itself for more details. 

A macro call consists of a macro name and a list of actual parameters, each separated by 
a comma. The name is preceded by a left square bracket ((), and the last parameter is 
followed by a right square bracket. A macro is defmed by the special macro DEF, which 
takes two arguments: the name of the macro to be defined and the defining string. The 
defining string may contain the special symbols -1, -2, etc., which .stand for the first, 
second, etc., formal parameters. Enclosing any string in parentheses prevents 
evaluation of any macro calls inside; in place of evaluation, one layer of string quotes is 
removed. It is usual to enclose the defining string of a macro definition in string quotes 
to prevent any macro calls or uses of formal parameters from being effective during the 
process of definition. 

Here are some sample macros and an example: 

— macro definitions 
[DEP,LSHIPT, (Lef tShif t Down)] 
[DEF,RSHIFT, (RightShif t Down)] 
[DEF,EitherShi£t, ( 

(LSHIFTl => -1; 
[RSHIFT] »>-!)] 

— trigger cases 
SELECT TRIGGER FROM 

BS Down «> SELECT ENABLE FROM 
[EitherShi£t,{BackWordn ; 
ENDCASE a> {Backspace}; 

— more cases . . . 
ENDCASE. . . 

The above example expands to: 

BS Down -> SELECT ENABLE FROM 
Le£tShift Down «> BackWord; 
RightShift Down »> BackWord; 
ENDCASE => {Backspace}; 
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Item Page 

actionToWindow: array of boolean 1 1 

ATOM: TYPE 4 

AttentionProc: TYPE 10 

backStoplnputFocus: window.Handle 7 

CaliBack: procedure 8 

CallBackNotifyProc: type 9 

CanceiPeriodicNotify: procedure 8 

caretRate: Process.Ticks 11 

CharTranslator: type 7 

CiearinputFocusOnMatch: procedure 7 

ClearManager: procedure 9 

clickTimeout: System. Pulses 11 

CreateCharTabie: procedure 6 

CreatePeriodicNotify: procedure 8 

CreatePiaceHolderTable: procedure 6 

CreateTabie: procedure 6 

Destroy Table: procedure 6 

DownUp: type 4 

Error: ERROR 11 

ErrorCode: type 1 1 

FlushUserlnput: PROCEDURE 11 

FocusTakesinput: procedure 7 

GetCharTranslator: procedure 8 

GetlnputFocus: procedure 7 

GetManager: procedure 9 

GetNotifierProcess: PROCEDURE 11 

GetNotifyProc: procedure 5 

GetNotifyProcFromTable: procedure 6 

GetPlace: PROCEDURE 11 

GetResults: procedure 12 

GetTabie: procedure 5 

GetTabieLink: procedure 5 

GetTabieOpacity: procedure 5 

InvalidTable: signal 11 

KeyBits: type 8 

KeyName: type 4 



Item 


Page 


KeyToCharProc: type 


7 


LosingFocusProc: type 


7 


Manager: type 


9 


NotifyProc: type 


4 


nuilManager: Manager 


9 


nutlPerlodicNotify: PeriodicNotify 


8 


PerlodicNotify: type 


8 


ResetUserAbort: procedure 


9 


ResultObject: type 


4 


Results: type 


4 


ResuitsWanted: type 


12 


ReturnToNotifier: error 


11 


SetAttention: PROCEDURE 


10 


SetBackStopi nputFocus : procedure 


7 


SetCharTranslator: procedure 


8 


Setl nputFocus: procedure 


7 


SetManager: procedure 


9 


SetNotifyProc: procedure 


5 


SetNotlfyProcForTabie: procedure 


6 


SetTabie: procedure 


5 


SetTableAndNotifyProc: procedure 


5 


SetTabieLink: procedure 


5 


SetTableOpacity: procedure 


5 


SetUserAbort: procedure 


9 


StuffCharacter: procedure 


10 


Stuff CurrentSelection: procedure 


10 


Stuff Results: procedure 


10 


StuffSTRING: procedure 


10 


Stuff String: procedure 


10 


StuffTrashBin: procedure 


10 


Table: type 


5 


TableError: type 


11 


TableObject: type 


5 


UserAbort: procedure 


9 
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48.1 Overview 

The TIP facility provides a mechanism that links a list of TiP.Tables. These TiP.Tables 
contain productions that translate user actions into terms a client is prepared to deal with. 
TIPStar creates a structure for the list of ViewPoint TIP tables to be built on. This 
structure divides ail possible input actions into logical groups (mouse actions, special keys 
like UNDO and STOP, utility keys like MOVE and COPY, etc.) and provides a means for 
accessing these groups of tables. 

48.2 Interface Items 

48.2. 1 The TIPStar Structure 

The basis for the TIPStar structure is the placeholder. 

Placeholder: type ■ {mouseActions, keyOverrides, softKeys, keyboardSpecific, 
blackKeys, sideKeys, backstopSpecialFocus}; 

A placeholder table is created for each of the enumerateds in Placeholder. Placeholder 
tables are empty TIP tables linked to form a list. This list divides all possible input actions 
into logical groupings as discussed in the Overview above. It defines a series of segments 
for the list of TiP.Tables to be built upon. Segments (mini-stacks) are delineated by the 
placeholder tables. This initial list of TiP.Tables then, contains only empty tables. Note: 
Placeholder tables are always empty. They are, as their name implies, placeholders-each 
providing a position in the list of tables for adding or removing real tables of a particular 
kind (those relating to mouse actions, those mentioning the soft keys,and*so forth.). See 
Examples in the next section. 

Fine point: A set of normal tables that contain all the basic key productions is installed at boot time. See the 
System TIP Tables Appendix for listings of those tables and a view of the TIP table list at the completion of 
booting. These normal tables are referred to as generic in the description of TiPStar.GetTabie to prevent confusion 
with the procedure TiPStar.NormalTable. 
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The list of ViewPoint placeholder tables is initialized as in Figure 48.1 (the arrows 
represent the links of the list). 



Placeholders 



mouseActions 



keyOverrides 



softKeys 



keybbardSpecific 



black Keys 



backstopSpeci ai Focus 



NIL 



input & Uses 



Point and adjust menu 



[e.g,. PROPS when a property sheet is up I 



Interprets top row of keys 



Keys on physically different keyboards 



The physical keyboard and its modifications. 



All those not directed to the input focus. 



Handles STOP, KEYBOARD, UNDO, and friends. 



Figure 48. 1 ViewPoint Placeholder Tables 



48.2.2 Installing and Removing Tables 

A client may alter the table arrangement by pushing or storing a TIP table into any point 
on the tree, or by popping back to a previous table. 

PushTable: procedure [Placeholder, TIP.Table] ; 

PushTable leaves old tables in the watershed, but places the new table (or chain of tables) 
directly after the specified placeholder. This places the new table in front of any others 
within that segment. Thus if the new table mentions the same key actions as the old table, 
the old one is effectively ignored until the new one is popped. If the new table only 
mentions a few key actions, however, previously pushed tables will be used for the others. 

For an example of PushTable and the resulting Tip.Table list, see §48.3. 1. 

PopTable: procedure [Placeholder, TiP.Table] ; 

PopTable takes the single TIP table to be popped. It is not required that the table to be 
popped be at the top of the placeholder's list. A strict stack discipline is relaxed. 
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StoreTabie: procedure [Placeholder, Tip.Table] returns [Tip.Table] ; 

StoreTable replaces the table (or chain of tables) with the client's table (or chain of tables) 
and returns the previous table. The client can restore the old value later, if it wishes. (In 
using StoreTabie, and especially in remembering or restoring the old value, the client 
probably needs to be cognizant of the other clients that may manipulate the same 
placeholder.) (See examples in §48.3.3.) 

48.2.3 Retrieving Pointers to Installed Tables 

NormalTabie: procedure returns [Tip.Table]; 

NormalTabie returns the table at the head of the list (mouseActions placeholder). This is 
the appropriate table to use for a normal Tip.SetTableAndNotifyProc. 

GetTable: procedure [Placeholder] returns [Tip.Table] ; 

GetTable returns the generic table at the specified placeholder, if one exists. (See the fine 
point in §48,2.1.) 

48.2.4 Mouse Modes 

Mode: type ■ {normal, copy, move, sameAs}; 

The TiPStar.Modes refer to the various modes attributable to mouse actions. These modes 
can be programmatically checked and changed by using the GetMode and SetMode 
procedures outlined below. 

GetMode: procedure returns [mode: Mode]; 

GetMode returns the current mode. 

SetMode: PROCEDURE [mode: Mode] returns [old: Mode]; 

Calling SetMode causes the appropriate Tip.Table to be stored in the Tipstar chain. 

For example, when the COPY key goes down, the call to TiPStar.SetMode(copyl causes 
NormalMouse.TIP to be relaced by CopyModeMouse.TlP. Clients receiving mouse notifications 
receive CopyModeDown instead of PointDown. If the world is in move mode (causing 
MoveModeMouse.TIP to be stored) the client receives the MoveModeOown when mouse 
point is pressed. See the TIP Table appendix for information on the other productions in 
the four mouse tables (NormalMouse.TIP, CopyModeMouse.TlP, MoveModeMouse.TIP and 
SameAsModeMouse. Tl P ) . 
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48.3 Usage/Examples 



48.3.1 When PushTable Is Called 

InitializeMyTIPTabies: procedure s 

BEGIN 

rbClientAMouse: xstrmg.ReaderBody xstring.FromSTRING["CiientAMouse.TiP"L]: 
tipClientAMouse: Tip.Table <~Tip.CreateTable(file: ©rbClientAMouse]; 

— install my tip table (tie it to my notify proc) 

(]4-TiP.SetNotifyProcForTable( tipClientAMouse. ClIentAMouseNotifyProc]; 
PushTabietmouseActions, tipClientAMouse]; 

rbClientAKeys: xstrmg.ReaderBody <-xstring,FromSTRfNGl"ClientAKeys.TiP"Ll; 
tipClientAKeys: Tip.Table <-Tip.CreateTable{file: @rbClientAKeys]: 

— install my tip table (tie it to my notify proc) 

Q4-TiP.SetNotifyProcForTable{ tipClientAKeys, ClientA.KeysNotifyProc]; 
PushTable(sideKeys. tipClientAKeys]; 
END; — InitializeMyTIPTabies 

Assume initially that the list appears as in Figure 48. 1. If Client A then pushes two tables 
onto that list, as in the code above, the new links result in the list shown in Figure 48.2.. 



1 



softKeys 



1 



keyboardSpecific 



blaclcKeys 



sideKeys 



mouseActions 




ClientAMouse.TIP 










key Overrides 


4 1 



> ClientAKeys.TIP 



backstopSpeciai Focus 



i 



NIL 



Figure 48.2 When PushTable Is Called 
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If client B then pushes another table to the mouseActions placeholder 
PushTabJe(mouseActions, tipClientBMouse]: 

the resulting list appears as in Figure 48.3. 



mouseActions 



keyOverrides 



softKeys 



keyboardSpecific 



black Keys 



sideKeys 



backstopSpecial Focus 



1 



NIL 



* ClientBMouse.TIP 



ClientAMouse.TIP 



> ClientAKeys.TIP 



Figure 48.3 Pushing Another Table 



48.3.2 When StoreTable Is Called 

rbClientCMouse: xstring.ReaderBody xstring.FromSTRING("CiientCMouse.TiP"L]: 
tipClientCMouse: Tip.Table Tip.CreateTable(f ile: ©rbClientCMouse): 
" install my tip table (tie it to my notify proc) 

U<-TiP.SetNotifyProcForTabie( tipClientCMouse. ClientCMouseNotifyProc]; 
savedTabie 4- StoreTabletmouseActions. tipClientCMouse]; 

Assume initially that the li.st appears as in Figure 48.3. if client C then calls StoreTable 
with another table directed at the mouseActions placeholder, the resulting list appears as 
in Figure 48.4. 
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mouseActions 



ClientCMouse.TIP 



keyOverrides 

1 

softKeys 



keyboardSpecific 



i 



black Keys 



sideKeys 



> ClientAKeys.TIP 



backstopSpecial Focus 



NIL 



Figure 48.4 Pushing Another Table 



Client C now has the handle to the segment removed from mouseActions when the 
StoreTabie was done (savedTable, see Figure 48.5). This table (or in this case, chain of 
tables) should be replaced when the client is through with its own mouse tip 
(tipCllentCMouse) by a call to: 



StoreTable[mouseActions, savedTable]; or 
PopTable(mouseActions, tipCiientCMousej; 
PushTable[mouseActions, savedTable]; 







ClientBMouse.TIP 






r 




ClientAMouse.TIP 







Figure 48.5 Saved Table 
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48.3.3 When PopTabie Is Called 



Assume initially that the list appears as in Figure 48.3. If client A then pops its table at 
the mouseActions placeholder, the resulting list appears as in Figure 48.6. Note: It is not 
necessary for the table being popped to be at the top of the stack (where the top of a stack is 
here defined to be the position immediately following any placeholder table—thus there 
are several stacks within the watershed list of tables). 



mouseActions 



> CiientBMouse.TIP 



keyOverrides 



softKeys 



keyboardSpecific 



blackKeys 



sideKeys 



► ClientAKeys.TIP 



backstopSpeciai Focus 



NIL 



Figure 48.6 Pop Table 
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48.4 Index of Interface Items 



Item 


Page 


GetMode: procedure 


3 


GetTable: procedure 


3 


NormalTable: procedure 


3 


Mode: TYPE 


3 


Placeholder: type 


1 


PopTable: procedure 


2 


PushTable: procedure 


2 


SetMode: procedure 


3 


StoreTable: procedure 


3 
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The Undo interface provides a set of procedures that allow applications to add Undo 
opportunities to the current Undo stack. An implementation of Undo can then call 
applications when the UNDO key is depressed. 

49.2 Interface Items 

49.2.1 Application's Procedures 

Opportunity: undo.Proc; 

PrOC: TYPE « PROCEDURE [ 

undoProc: procedure [long pointer], 
destroyProc: procedure [long pointer], 
data: long pointer, 
size: cardinal «- 0 ]; 

The Opportunity procedure is called by an application when it does something that can be 
undone. The client's undoProc is called to perform an undo. The destroyProc is called 
when the undo opportunity no longer exists. The client can destroy any data at that time. 
The undoProc or the destroyProc will always be called. The client's context for the 
undoing is passed in via the data item: a non-zero size indicates that the Undo 
implementation should copy the words from data | through (data + size-1) f into its zone. 
If size = 0, the caller's long pointer is simply remembered. 

Roadblock: procedure [xstring.Reader]; 

4 

The Roadblock procedure is called by an application when it does something that cannot 
be undone. The immutable string passed in is a message that the Undo implementation 
can issue if the user attempts to undo past this point. The string is copied. - 

DoAnUndo: procedure; 
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The DoAnUndo procedure is called when an undo action should be forced. This is typically 
when the keyboard modules notice that UNDO has been pressed. 

OoAnUnundo: proceoure; 

The OoAnUnundo procedure is called when an un-undo action should be forced. This is 
typically when the keyboard modules notice that shift-UNDO has been pressed. 

DeleteAII: procedure; 

The DeleteAII procedure is called to tell the Undo implementation to empty its stack of 
opportunities. This procedure is typically called upon logofT. 



49.2.2 Implementation's Procedures 

Setlmplementation: procedure [ 

undo.lmplementation] returns [implementation]; 

Getlmpiementation: procedure returns [Implementation]; 

implementation: type ■ record [ 
opportunity: undo.Proc, 
roadblock: procedure [xstnng. Reader], 
doAnUndo: procedure, 
doAnUnundo: procedure, 
deieteAll: PROCEDURE ]; 



These procedures allow an implementation to plug itself in to the Undo mechanism. An 
implementation can supply its set of procedures and can ascertain the current procedures. 
Setlmplementation returns the procedures of the previous implementation. 

An initial set of dummy procedures are provided. They are basically no-ops; the dummy 
Opportunity procedure immediately calls the application's opportunlty.destroyProc. 

Zone: procedure returns [uncounted zone] 

Returns the implementation's zone. 



49.3 Usage/Examples 

The application calls Opportunity with some conte.xt. The Undo implementation 
eventually calls the application either at its undoProc or its destroyProc. The former is 
called upon a real undo request. The latter is called when the opportunity is about to be 
forgotten: it allows the application to garbage-collect conte.xt. The destroyProc is typically 
called to prune the undo stack of very old elements or to prune' opportunities that are 
trapped behind a roadblock. 



At the application's undoProc or destroyProc, the argument is either (1) the original 
pointer passed in to Opportunity, if size was zero or (2) a pointer into the Undo 
implementation's zone that points to a copy of the application's data. In the latter case, the 
data is freed by the Undo implementation right after the call. Exception: if the help 
implementation is a no-op implementation, it can call the application's destroyProc from 
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inside the Opportunity call. In this case, the help implementation can present the original 
pointer to the destroyProc even if size is non-zero. 

49.3.1 Example 

MyllndoOataObject: type > record [...]; 

MyUndoOata: type « long pointer to MyUndoOataObject; 

complaint: xstrirtg.ReaderBody 4*xstring.FromSTRlNG ["Can't do that^L]; 

UndoProc: PROCEDURE [my UndoOata: MyUndoOata] ■ { 

does something appropriate, lilce a partial cleanup of data structures.message 

might post a about current state for the user. 
undo.Zone [].FREE [@my UndoOata] ; 
}; 

DestroyProc: procedure [myUndoOata: MyUndoOata] a { 
Undo.Zone [].FREE [©myUndoOata]; 

}; 

— Mainline code 

" Code that cannot be undone 

undo.Roadblock [©complaint]; 

- Code that can be undone 

Undo.Zone[].NEw[MyUndoOataObject [...] ]; 

undo.Opportunity [undoProc: UndoProc, destroyProc: DestroyProc, data: myOata]; 
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49.4 Index of Interface Items 



Item Page 

OeieteAli: PROCEDURE 2 

OoAntlndo: procedure 1 

DoAnUnundo: procedure 2 

Getlmptementation: procedure 2 

implementation: type 2 

Opportunity: procedure 1 

Proc: TYPE 1 

Roadbiocic: procedure 1 

Setlmplementation:PROCEDURE 2 

Zone: procedure 2 
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50.1 Overview 

UnitConversion provides for converting numbers between various units of measure. 

50.2 Interface Items 

Units: type ■ {inch, mm, cm, mica, point, pixel, pica, didotPoint, cicero}; 

Units defines all the units that may be converted, point is printer point, pixel is screen dot. 
pica = 12 points. 

ConvertReal: procedure [n: XLReai. Number, inputUnits, outputUnits: Units] 
RETURNS [xLReal.Number]; 

ConvertReal converts n from InputUnits to outputUnits, using XLReai. May raise 
XLReal.Error. 

Convertlnteger: procedure [n: long integer, inputUnits, outputUnits: Units] 

RETURNS [long INTEGER]; 

Convertlnteger converts n from inputUnits to outputUnits. May raise XLReal.Error. 

50.3 Usage/Examples 

50.3.1 Converting Font Values 

The following example implements a real-number conversion utility: 

Unit: TYPE a MACHINE DEPENDENT {inch(O), mm(1), mica<2), point(3), space(4), cm(5), (15)}; 

Convert: public proc [n: XLReai. Number, inputUnits, outputUnits: Unit.Units] 
RETURNS [xLReal.Number] ■ { 
IF inputUnits ■ outputUnits then return [n]; 
IF inputUnits ■ space then 

RETURN 

UnitConversion.ConvertReal[ 
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XLReal.Muitiply[n, pointPerSpace],seventySecondOfAninch, 
Con vertU n its[outputU nits]] ; 
IF outputUnits ■ space THEN 

RETURN 

XLReai.Oivide[unitconversion.ConvertReal[n, ConvertUnits[inputUnits], 
seventySecondOfAnlnch], pointPerSpace]; 

RETURN 

unitConversion.Con vertReal [ 

n, ConvertUntts[inputUnits], ConvertUnits{outputUnits]]}; 

ConvertUnits: PROC[u: Units] RETURNS [unitConversion.Units] ■ { 
iFu < mica THEN RETURN [val[u.ORO]]; 
iFu a mica THEN RETURN [val[u.ORD •(•I]]; 
IFU ■ point THEN RETURN [val[u.ORD + 6]]; 

RETURN [cm] 

}; 
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50.4 Index of Interface Items 

Item Page 

Convertinteger: procedure 1 

ConvertReai: PROCEDURE 1 

Units: type 1 
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51.1 Overview 

The Window interface supplies facilities for managing windows on the display screen. A 
window is a rectangular region of the display screen in which a client can display 
information to the user. A window may overlap another window or even completely cover 
it. A window may extend past the edges of the physical display screen or even be 
completely outside it and thus not visible. Windows may be moved around horizontally 
and vertically, have their size changed, and have their depth changed in the stack of 
windows visible on the screen. Window shields the client from these considerations-from 
the client's point of view, each window is unaffected by other windows or by the edges of 
the display screen. Window automatically handles client requests to paint into window 
regions that are not currently visible on the screen. 

The Display interface supplies routines for painting into windows. 

51.1.1 Window Creation 

Window supplies operations to allocate and free a window (a window.Object). However, 
windows are usually not allocated directly by clients but are obtained from various other 
facilities, such as StarWindowShell or FormWindow. Once allocated, a window is referred 
to and manipulated by reference, using a window.Handle. 

51.1.2 Child Windows and the Window Tree 

Window manipulates a tree of windows. A window may have child windows. Child 
windows obscure their parent; that is, they are above their parent in the apparent stack of 
windows visible on the screen. A child window may be entirely contained within its 
parent's screen area, may project beyond its parent's edges, or may even be completely 
outside its parent. Window automatically clips the display of a child window at its 
parent's edges. Thus a child window that is completely outside its parent is not visible on 
the screen at all. 

Each window has an ordered list or stack of its child windows. Sibling windows may 
overlap: if they do, one that appears earlier in the stack is on top of or obscures one that 
appears later. The first window in the stack is the top sibling, and the last is the bottom 
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sibling. Each window has a pointer to its parent, a pointer to the next sibling of its parent, 0^ 
and a pointer to the window's topmost child. 

When a window is created, it is not in the window tree and is called a private window. A 
private window is unknown to Window and is not displayed on the screen. Window 
provides facilities for inserting private windows into the tree, moving them within the 
tree, and removing them from it. A window that is in the tree will be wholly or partially 
visible on the screen unless it is entirely outside its parent's area or unless its children 
completely cover the portion that is within its parent. Private windows may also be built 
into private treeSy which can be inserted into and removed from the window tree as a unit. 

Display supplies the root window, which is the root of the window tree and corresponds to 
the entire display screen. The root window typically supplies the background pattern. 

Each window has its own coordinate system: the upper-left corner is the origin [x; 0, y: 0], 
with X increasing to the right and y increasing downward. A window's location is defined 
in terms of its parent's window coordinate system. Coordinates may be positive or • 
negative, and thus a window can have any location relative to its parent. 

51.1.3 Painting into a Window 

Every window contains a client-supplied display procedure that will, on demand, paint all 
or part of the window. Note that windows can be much larger than the display screen; any 
paint directed to non-visible portions of a window-or outside the window entirely-is _ 
discarded. Thus a client never needs to be concerned about what parts of its window are 
covered by other windows or what parts are off the screen. As a convenience to clients, 
requests to paint into a window that is not currently in the window tree are also ignored. 

The Display and SimpleTextDisplay interfaces provide a variety of procedures for painting 
various things into a window, including character strings, black, white, or gray boxes, and 
various graphics, such as curves and lines. 

The display background color, which is represented by a pixel value of zero, is commonly 
called white and a value of one is called black. Note: The display hardware also can render 
the picture using zero for black and one for white. Clearing or erasing an area of the screen 
means setting all of its pixels to zero, or white. 

A display procedure usually wants to start with an erased (zero) area and logically OR the 
black pixels into the area. Window supplies an accelerator clearingRequired to minimize 
unnecessary erasures. If clearingRequired • true, Window guarantees that when the 
display procedure is called to paint the window, all of the window's pixels that should be 
white indeed are white. In that situation, the window might contain any combination of 
its previous contents and erased areas. On the other hand, some display procedures want 
to set all pixel values, completely overwriting the previous contents. These windows 
should specify clearingRequired a false. 

Areas displayed on the screen may become incorrect or invalid for many reasons, such as 
when a window that was visible is deleted. A client can also mark an area invalid. 
Window accumulates these invalid areas and then, in response to a client call to Validate 
or ValidateTree, calls the various windows' display procedures to paint the necessary 
areas. Validate and ValidateTree are the only Window operations that cause immediate 
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screen painting. All other operations merely enqueue work to be performed by a later 
Val idate operation. Fine point: The few special cases that do not follow this rule are noted in the text. 

The standard way for a client to paint into its window is to update its data structures, 
invalidate the portion of its window that needs to be painted, and then call a Validate 
routine. Window responds by calling back into the client's display procedure to do the 
painting. 

When a window's display procedure is called, it has access to a list of the invalid areas of 
the window (see EnumerateinvaiidBoxes). It may choose to paint the entire window or, 
alternatively, to enumerate the invalid areas and just paint those areas. In any case, 
Window clips all the display routine's paint requests to the boundaries of the invalid 
areas-paint directed to other areas is discarded. In special circumstances, the client may 
wish to paint into valid visible areas. The operation FreeBadPhosphorList deletes the 
display routine's invalid area list; for the lifetime of that invocation of that display 
procedure, paint requests are clipped only to the boundaries of the visible parts of the 
window. 

If display routines are called from outside the invocation of a window's display procedure, 
the paint requests will be clipped to the boundaries of the visible parts of the window. 

31.1.4 Bitmap-under 

The window package allows clients to associate a window with a bitmap-under. This is a 
block of memory that is used to hold the pixels that are covered up by the window. It allows 
Window to move or delete such a window quickly, 'since it can repaint the display directly 
by using the contents of the bitihap-under instead of calling client display procedures. A 
bitmap-under is commonly used for menu windows. 

31.1.5 Window Panes 

The window package normally maintains a detailed list of invalid regions and allows 
arbitrary overlapping of windows without requiring the client to worry about other 
windows. Some clients would prefer to have greater control over their windows at the 
expense of more restrictions over their use. Window panes are such a mechanism. If a 
window is a window pane, the client must ensure that it does not overlap any of its siblings 
and that the parent does not paint underneath the pane. A further restriction is that only 
window panes may be children of panes. In return, the window package can do much less 
calculation to determine invalid regions. The window package does not enforce these 
restrictions. It is up to the client to follow them, or the screen appearance maybe 
inconsistent. The client must specify whether a window is a window pane when it is 
initialized. 

51.2 Interface Items 

31.2.1 Basic Data Types and Utility Operations 

This section describes basic Window data types and utility procedures. 
Handle: type » long pointer to Object; 
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Object: type [19]; 

Object is the storage that represents a window. A Handle is used to refer to the window. 
Clients should not allocate objects directly but must use operations described in §51.2.2. 

rootWindow: readonly Handle; 

Root: PROCEDURE RETURNS [Handle] ■ INLINE {RETURN[rootWlndow]}; 

rootWindow is the window that is the root of the window tree. The procedure Root is 
provided for compatibility with previous versions; new applications should use 
rootWindow instead. 

MinusLandBitmapUnder: type [6]; 

MinusLandBitmapUnder is additional storage for windows that may have bitmap-unders. 
MinusLandColor: type [1]; 

MinusLandCoior is not used in the current release. 
MinusLandCookieCutter: type [2]; 

MinusLandCookieCutter is not used in the current release. 
Place: type * userT«rminai.Coordinate; -- [x, y: integer]; 

Place is a position in a window. It is measured relative to the window's upper- left corner, 
which is defined to be at [x: 0, y: 0]. x increases to the right, y increases downward. Note 
that the coordinates may be negative. 

Dims: type » record [w, h: integer]; 

Dims is the size of a rectangular box. The rectangle is w pixels wide and h pixels high. 
Box: TYPE * RECORD [place: Place, dims: Dims]; 
BoxHandle: type * long pointer to Box; 
nuilBox: Box « [place: [0, 0], dims: [0, 0]]; 

Box describes completely a rectangular box. place describes the upper-left pixel of the box, 
and dims describes the size of the box. The box extends to the right and downward from 
place. As always, place is expressed in its containing window's coordinate system. 

BoxesAreOisjoint: procedure [a, b: Box] returns [boolean]; 

BoxesAreOisjoint returns true if a and b do not intersect. 

IntersectBoxes: procedure [b1, b2: Box] returns [box: Box]; 
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IntersectBoxes returns a Box that is the intersection of b1 and b2. If their intersection is 
empty, this operation returns box.dims ■ [0, 0]. 

IsPtacelnBox: procedure [place: Place, box: Box] returns [boolean]; 

IsPlacelnBox returns true if place is a pixel of box. 

BitmapPlace: procedure [window: Handle, place: Place <- [0,0]] returns [Place]; 

BltmapPlace returns the coordinates in the root window that correspond to place in 
window. 

BitmapPiaceToWindowAndPlace: procedure [bitmapPlace: Place] 
RETURNS [window: Handle, place: Place]; 

BitmapPiaceToWindowAndPlace returns the topmost visible window and the coordinates 
within it that correspond to bitmapPlace in the root window. 



51.2.2 Window Creation and Initialization 



A window is created by the client allocating and initializing a window.Object. Many times 
windows are not created directly by clients, but rather are obtained from various other 
facilities, such as StarWindowShell or FormWindow. 

To create a window, the client allocates a window.Object using New, initializes it using 
Initialize, and presents it to Window for use using InsertintoTree. When the window is of 
no further use, it is withdrawn from Window using RemoveFromTree, and the storage is 
freed using Free or FreeTree. 

New: PROCEDURE [ 

under, cookie, color: boolean *- false, zone: uncounted zone 4- nil] returns [Handle]; 

New allocates a window object. If zone is nil, a cache of objects is used. A client should 
never call zone.NEw[window.Object] because the window object will not be properly 
initialized. 

Initialize, InitiallzeWindow: procedure [ 

window: Handle, display: DisplayProc, box: Box, 
parent: Handle <- rootWindow, sibling, child: Handle nil, 
clearingRequired: boolean <- true, windowPane: boolean <~ false, 
under, cookie, color: boolean false]; 

DisplayProc: type - procedure [window: Handle]; 

Initialize and InitiallzeWindow initialize the window object at window | . This must be 
done before the window is inserted into the window tree. The window is initially not a part 
of the window tree. It may be created as an isolated window or may be linked to other 
private windows to form a private tree, display is the client procedure for repainting the 
window, box is the window's size and parent-relative location, parent is the window's 
parent, sibling is the sibling immediately below the window in the sibling stack of parent 
and child is the top child of the window, parent, sibling, and child may be nil. 
clearingRequired is described in §51.1.3. windowPane is described in §51.1.4. under 
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indicates that the window can be associated with a bitmap-under. cookie and color are not 
supported in the current release; clients should default this parameter for compatibility 
with future versions. 

Create: procedure [ 

display: DispiayProc, box: Box, 

parent: Handle <- rootWindow, sibling, child: Handle «-NiLr 
ciearingRequired: boolean <-true, windowPane: boolean 4- false, 
under, cookie, color: boolean <~ false, zone: uncounted zone 4-nil] 
RETURNS (Handle] ■ inline 

Create is an inline that follows a call to New with a call to Initialize. 

Free: procedure [window: Handle, zone: uncounted zone <- nil]; 

Free frees a window object. If zone is nil, the window is returned to the cache of objects 
maintained by Window; otherwise it is freed to the zone. Any contexts associated with the 
window, via the Context interface, are not freed. Free may raise Error[invalidParameters] 
if the window had already been freed, if the window is still in the window tree, if the zone 
is nil but was not nil on the call to New, or if the zone is non-NiL but was nil on the call to 
New. 

FreeTree: procedure [window: Handle, zone: uncounted zone nil]; 

FreeTree frees the window and all its children, children first, and frees all contexts on 
windows in the subtree whose root is window.. Clients should almost always call FreeTree 
rather than Free. FreeTree may raise Error[invalidParametersI if the windows had already 
been freed, if the windows are still in the window tree, if the zone is nil but was not nil 
when the windows were allocated, or if the zone is non-NiL but was nil when the windows 
were allocated. FreeTree assume all the windows were allocated with the same zone if it is 
non-NiL. 

31.2.3 Access to and Modification of a Window's Properties 

The Get procedures below return properties of a window. The Set procedures change 
properties and return the previous value. These properties of a window are described in 
this chapter's overview. 

GetOisplayProc: procedure [Handle] returns [DisplayProc]; 

SetDisplayProc: procedure [Handle, DisplayProc] returns [DisplayProc]; 

GeKlearingRequired: procedure [Handle] returns [boolean]; 

SetClearingRequired: procedure [window: Handle, required: boolean] 
RETURNS [old: boolean]; 

GetParent: procedure [Handle] returns [Handle]; 

GetSibling: procedure [Handle] returns [Handle]; 
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GetSibling returns the next lower sibling of the argument window. 

GetChild: procedure [Handle] returns [Handle]; 

GetChlld returns the topmost child of the argument window. 

See also §51.2.4 for Set procedures that change a window's links to its parent, siblings, and 
child. 

EntireBox: procedure [Handle] returns [Box]; 

EntireBox returns the box [[0, 0], window.dims]. It is handy for invalidating the entire 
window. 

GetBox: procedure [Handle] returns [Box]; 

Note that there is no SetBox; SlideAndSize should be used instead. 
GetPane: procedure [Handle] returns [boolean]; 

GetPane returns whether or not the window is a window pane. The window pane property 
can only be set when the window is initialized. 

IsCookieVariant: procedure [Handle] returns [boolean]; 

Cookie cutters are not supported by the current release. IsCookieVariant should always 
return FALSE. 

IsCoiorVariant: procedure [Handle] returns [boolean]; 

Color is not supported by the current release. IsCoiorVariant should always return false. 

51.2.4 Window Tree and Window Box Manipulation 

Basic operations are provided for constructing private trees from private windows and for 
inserting them into and removing them from the window tree. Other operations allow 
moving a window within a window tree and changing a window's location and size. Special 
operations are provided to perform common combinations of these operations. 

Most clients obtain windows from some higher-level facilitiy like Form Window; in such 
cases, the window typically has already been inserted into the window tree. Thus most 
clients will only use the following operations: Stack, Slide, SlideAndStack, SlideAndSize, 
SlideAndSizeAndStack. 

Unless otherwise noted, all these operations may be applied either to windows in the 
window tree or to windows in a private tree. Operations performed on windows in private 
trees change tree links and the window's box but naturally create no invalid regions on 
the display. 

As described in the overview, none of the operations in this section perform screen 
painting. They merely enqueue painting work to be performed by a later Validate 
operation. 
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IsDescendantOf Root: procedure [Handle] returns [boolean]; 

isOescendantOf Root returns true if window is currently a part of the window tree. 

ObscuredBySibling: procedure [Handle] returns [boolean]; 

ObscuredBySibiing returns true if the box of any higher sibling intersects window's box. 

EnumerateTree: procedure [root: Handle, proc: procedure [window: Handle]]; 

EnumerateTree calls proc for every window in the tree rooted at root. The order of 
enumeration is not specified. Altering the tree while an enumeration is in progress causes 
unpredictable operation. 

The following three operations allow constructing private trees from private windows. 

SetParent: procedure [window, newParent: Handle] returns [oldParent: Handle); 

SetSibiing: procedure [window, newSiblIng: Handle] returns [oldSibiIng: Handle]; 

SetChtId: procedure [window, newChild: Handle] returns [oldChild: Handle]; 

These Set procedures set the parent, next lower sibling, or topmost child of window. No 
list manipulation nor consistency checking is done-these operations merely store their 
argument into the window object. If window is in the window tree, Error[windowlnTree] 
is raised (Stack, et al. can be used in that case). If inconsistent calls to the Set procedures 
are made, Error(windowNotChildOfParent] is raised when some subsequent operation 
detects the inconsistency. 

InsertlntoTree: procedure [window: Handle]; 

InsertlntoTree inserts a private window or subtree into any window tree, window is 
inserted as a child of window.parent. window is immediately above window. sibling in 
the sibling stack of the new parent: window.sibling a nil makes it the bottommost 
sibling, window.chiid is the topmost child of a private tree that descends from the 
window~NiL if none. All of these fields of window may be set by using the Set procedures 
described above. The client can force painting of the windows just inserted by doing 
window.GetParent[].ValidateTree[]. Error[noSuchSibilng] may be raised. Fine point: 

InsertlntoTrae does not normally cause any painting activity. However, if a window that has a bitmap-under is 
inserted into the tree and the content of the bitmap is not available on the display, Validate Tree is done on that 
window's parent to obtain the content of the bitmap. 

RemoveFromTree: procedure [Handle]; 

RemoveFromTree removes the window and all of its descendants from its containing tree. 
The window becomes the property of the client. The descendants of the window remain 
attached to it. The entire subtree may be later inserted back into a tree by using 
InsertlntoTree. The client can force painting of now-incorrect areas of the display by 
applying ValidateTree to any parent of the removed window. Caution: The sibling pointer 
of the removed window remains pointing to its former sibling in the tree. A client should 
take care that the sibling pointer of the window is set to the desired, valid in-tree sibling 
(or NIL) before doing a subsequent InsertlntoTree. 
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Stack: procedure [window: Handle, newSibling: Handle, newParent: Handle <~ nil]; 

^iHi^ Stack changes window's location in its window tree, thus changing the window's depth in 

the apparent stack of windows on the screen. If newParent is not nil, then window is 
moved to be a child of newParent; otherwise, its parent is unchanged. Next, the sibling 
stack then containing window is modified so that window is now immediately above 
newSibling, thus potentially obscuring siblings lower on its sibling stack. Supplying 
newSibling • nil puts window on the bottom of the sibling stack. Unless window is 
already the top sibling, supplying newSibling ■ window.GetParent.GetChild[] puts 
window on the top of the stack. Caution: If window is the top sibling, the previous 
expression is a client error that is not guarded against. If one of window or newParent is 
in the window tree but the other is not, Error[lllegalStack] is raised. Error[noSuchSibling] 
may also be raised. 

Slide: procedure [window: Handle, newPlace: Place); 

Slide changes window's position relative to. its parent. This procedure may be used to 
implement scrolling. Error[whosSiidingRoot] may be raised. 

SiideAndStack: procedure [ 

window: Handle, newPlace: Place, newSibling: Handle, newParent: Handle nil]; 

SiideAndStack performs a Stack and then a Slide, thus changing window's location in its 
tree and its position within its new parent. Error[iliegalStack], Error[noSuchSibling], and 
Error[whosSlidingRoot] may be raised. 

Gravity: type ■ {nil, nw, n, ne, e, se, s, sw, w, c, xxx}; 

Gravity indicates where the old pixel content of a window should go when it changes size. 
This allows Window to reuse any current window content that will be visible in its new 
configuration. 

nil The contents remain at their current screen position (not 

their window-relative position). 

nw, n, ne, e, se, s, sw, w The contents stay attached to the indicated compass point of 

the window, which is either a corner or the middle of a side; 
for example, nw means the contents stay in the upper- left 
corner. 

c The contents go in the middle of the new window-trimming 

or expansion occurs equally at opposite edges. 

xxx The contents are discarded. 

StideAndSize: procedure [window: Handle, newBox: Box, gravity: Gravity nw]; 

SlideAndSize changes both the location and size of window, gravity indicates what to do 
with the current contents of the window. Error[sizingWithBitmapUnder] and 
Error[whosSlidingRoot] may be raised. 

SlideAndSizeAndStack: procedure [ 
"iiiaa/ window: Handle, newBox: Box, newSibling: Handle, newParent: Handle ^ NIL, 

gravity: Gravity ♦-nw]; 
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SlideAndSizeAndStack performs a Stack and then a SlideAndSize, thus changing 
window's location in its window tree and its position and size within its new parent. 
Error[iilegaiStack], Error[noSuchSibling], ErrorfsizingWithBitmapUnder], and 
Error[whosSlidingRoot] may be raised. 

Slidelconicaliy: procedure [window: Handle, newPlace: Place]; 

Stidelconically is not implemented in the current release. 

51.2.5 Causing Painting 

A general description of painting is given in §51.1.3. The procedures below are used both 
to cause areas of the screen to be painted and actually to do the painting. 

InvalidateBox: procedure [window: Handle, box: Box, clarity: Clarity <~ isOirty]; 

Clarity: type « {isCiean, isOirty}; 

InvalidateBox declares that the current screen content of box in window is incorrect. 
Window adds box to the list of invalid regions of the window, clarity indicates the current 
state of the box. clarity ■ isClean means the region is already erased (all white); isDirty, 
that it contains some black. Window uses this information to avoid unnecessary clearing. 
InvalidateBox does not cause immediate display painting; only the Validate procedures do 
that. Note that a call on InvalidateBox followed by a call on Validate may result in no call 
to the display procedure—for example, if the invalidated area is not visible. If the window 
is not in the window tree, this operation does nothing. 

Validate: procedure [window: Handle]; 

ValidateTree: procedure [window: Handle rootWindow]; 

Validate and ValidateTree are the only Window procedures that cause immediate display 
painting. Fine point: The few special cases that do not follow this rule are noted in the text. Validate acts 
only on window; ValidateTree acts on the tree whose root is window. Typically, a client 
updates its data structures and invalidate various regions. When the client is ready to 
have the display updated, one of the Validate procedures is called. If window is not in the 
window tree, this operation does nothing. 

EnumeratelnvaiidBoxes: procedure [window: Handle, proc: procedure [Handle, Box]]; 

EnumeratelnvalidBoxes is used within a window's display procedure to obtain the list of 
invalid regions of the window. EnumeratelnvalidBoxes calls proc for each of the invalid 
boxes of window; window is passed to proc as its first argument. The second argument of 
proc describes the region that is invalid. Note: A display procedure need not worry about 
redundant painting outside the invalid regions; Window automatically discards the 
display procedure's paint that falls outside the invalid regions. This operation must only 
be called from within a display procedure, and window must be the window argument of 
the display procedure. 
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FreeBadPhosphorList: procedure [window: Handle]; 

In special circumstances, a display procedure may wish to paint into valid visible areas. 
FreeBadPhosphorList deletes the display procedure's invalid area list; for the lifetime of 
that invocation of that display procedure, paint requests are clipped only to the visible 
parts of the window. This operation must only be called from within a display procedure, 
and window must be the window argument of the display procedure. 

TrimBoxStickouts: procedure [window: Handle, box: Box] returns [Box]; 

TrimBoxStickouts returns a box that is the result of excluding any portion of box that 
sticks out of window or its ancestors. Display procedures may find it useful. 

51.2.6 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type « { 

illegalBitmap. illegalFloat, windowNotChildOfParent, whosSlidingRoot, 
noSuchSibling, noUnderVariant, windowinTree, sizingWithBitmapUnder, 
illegalStack, invalidParameter}; 

iilegalBitmap A window passed to SetBitmapUnder is not totally visible. 

iliegalFioat See Float. 

windowNotChiidOfParent A window is not in the list of its parent's children. This 

usually means that inconsistent calls to SetParent, 
SetChild, or SetSibiing were made. 

The client has attempted to move the root window. 

An operation moving a window in the window tree 
specifies a new sibling that is not a child of the new parent. 

A bitmap-under operation was applied to a window that 
may not have a bitmap-under associated with it. 

SetParent, SetSibiing, or SetChild was applied to a window 
in the window tree. Stack, et al., can be used instead. 

A client has tried to change the size of a window that 
currently has a bitmap-under. 

The client is attempting to move a window between 
parents, one of which is in the window tree and the other is 
not. 

The client has invoked an operation with invalid 
parameters. 



whosSlidingRoot 
noSuchSibling 

noUnder Variant 

windowlnTree 

sizingWithBitmapUnder 

illegalStack 

invalidParameter 
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51.2.7 Special Topic: Bitmap-Under i^ll 
Bitmap-unders are described in §51.1.4. Most clients have no need for bitmap-unders. 
IsBitmapUnderVariant: procedure [Handle] returns [soolean]; 

IsBitmapUnderVariant returns true if the window can be associated with a bitmap-under 
(that is, if lnitiaiizeWindow[ .... under: true]. 

WordsForBitmapUnder: procedure [window: Handle] returns [cardinal]; 

WordsForBitmapUnder returns the number of words of storage needed for a bitmap-under 
corresponding to the current size of window. 

SetBltmapUnder: procedure [ 

window: Handle, pointer: long pointer <~ nil, 
underChanged: UnderChangedProc *- nil, 

mouseTransformer: MouseTransformerProc 4- nil] returns [long pointer]; 
JnderChangedProc: type ■ procedure [Handle, Box]; 

MouseTransformerProc: type ■ procedure [Handle, Place] returns [Handle, Place]; 

SetBltmapUnder associates a bitmap-under with window, pointer describes a scratch 
storage area for the bitmap-under; its length must be as given by WordsForBitmapUnder. ^^ni 
If pointer ■ nil, the window ceases to have a bitmap-under. The pointer to any previous 
bitmap-under is returned; the client becomes the owner of that storage. The 
underChanged and mouseTransformer parameters are ignored in the current release. If 
the window cannot be associated with a bitmap-under, Error(noUnderVariant] is raised. If 
the window is in the window tree but is obscured by another window, Error(lllegaiBitmap] 
is raised. While the bitmap-under is in effect, the window's size cannot be changed; an 
attempt to do so will raise Error[sizingWithBltmapUnder]. 

GetBitmapUnder: procedure [window: Handle] returns [long pointer]; 

GetBitmapUnder returns the pointer to the current bitmap-under for window; returns nil 
if none. If the window cannot be associated with a bitmap-under, Error[noUnderVariant] 
is raised. 

Float: procedure [window, temp: Handle, proc: FloatProc]; 

FloatProc: type « procedure [window: Handle] returns [place: Place, done: boolean]; 

Float moves a window continuously on the screen. Float first forces window to the top of 
its sibling stack, next does ValidateTree[rootWindow], and then enters a loop for 
changing the window's position. In the loop, Float calls proc, passing window to it. If proc 

returns done ■ TRUE, the operation terminates and Float returns to the client. Otherwise, 
Float moves the window to place and repaints the display. It does so without calling any 
client display procedure; control returns to the top of the loop. The client must ensure that jm 
the window is wholly visible when moved to place, temp is used for temporary storage for 
the duration of the float operation, temp must be the same size as window, have a bitmap- 
under, and not be in the window tree. If window is not in the window tree, if temp is in the 
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window tree, if either window lacks a bitmap-under, or if tiie windows have different sizes, 
Error[illegalFioat] is raised. 

51.3 Usage/Examples 

A scrollbar is an example of a simple window. An entire StarWindowSheli window is an 
example of a window that has many descendant windows~-the window header, the 
scrollbars, and the main interior window used to display the content. 

Window shields the client from interference between windows and from the presence of 

the edges of the display screen. A client can freely move a window around on or off the 
screen and alter its position in the stack of windows; Window automatically handles the 
overlapping. 

Window automatically clips painting into windows to the visible interior of its parent 
v-indow. A client can freely paint anywhere inside or even outside of its window as 
convenient. 

I: is always correct to paint more of a window than the minimum required. Simple clients 
nay adopt a simple repaint strategy, invalidating and/or repainting a large part or even 
eil of a window. Sophisticated clients may invalidate only the necessary parts of a window, 
tnus allowing only small amounts of repainting and minimizing references to the 
window's backing data. This may result in improved performance. 

A display procedure has available to it a list of invalid areas that need to be repainted. 
However, it may adopt the simple approach of ignoring this data and repainting the entire 
window. In any case. Window clips a display procedure's paint to the boundaries of the 
invalid regions. 

Areas that project outside of a window's parent are trimmed for display purposes. Vertical 
scrolling can be implemented quite simply by embedding a tall content window in a short 
clipping window and then just Slideing the position of the content window within the 
clipping window. Horizontal scrolling can be done in a similar way. The StarWindowSheli 
interface supports this method of scrolling. This approach is limited by the domain of the 
coordinates, which are integers. Scrolling in this way is limited to +-2 1 15 pixels offset 
from the frame window. If more scrolling than this is required, the client cannot use this 
technique, but must itself perform the transformation from data coordinates to window 
coordinates. 

Since a window's location is defined in its parent window's coordinate system, moving a 
window automatically moves all of its descendant windows along with it. 

Window itself has nothing to do with the keyboard and mouse. However, the TIP interface 
provides the facility for associating mouse and keyboard actions with a window. 

31.3.1 Display Procedures and monitors 

Any process may manipulate windows and thus cause screen painting activity. Even if one 
client always runs in the Notifier process, its window's display procedure may be called at 
any instant because of asynchronous activities by some other process. If a window's 
display procedure uses any nonlocal variables in its painting activity { the usual case), those 
variables must be protected by a MONITOR. Most display procedures are monitor entry 
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procedures. Of course, if the display procedure only refers to immutable data, its operation 
need not be monitored. 

Since a display procedure is usually a monitor entry, the client must avoid deadlocks by 
not invoking the display procedure from within other monitor procedures. This is the 
standard rule for monitors. Because calling Validate may cause Window to call the 
client's display procedure, calls to Validate must be done outside the client's monitor. The 
normal arrangement is (1) enter monitor, (2) update monitor data and Invalidate regions, 
(3) exit monitor, (4) Validate (which causes the display to be repainted). 

31.3.2 Example 

- These excerpts are taken from <BWSHacks> 1.0>Source>Puzzle15lmpLmesa 

boxSize: CARDINAL « 32; 

boxDims: window.Oims ■ [boxSize, boxSize]; 

bodyWindowOims: window.Oims « [boxSize*grid + 2, boxSize*grid * 2]; 
boxes: ARRAY [0..max) OF window.Box; 

IWenuProc: MenuOata.MenuProc ■ { 

another: xstring.ReaderBody xstring.FromSTRING("Another"L]; 
rb: xstring.Reader8ody xstring.FromSTRiNG["1 5 Puzzie"L]; 
shell: starWindowSheii.Handle « starwindowSheii.Create [name: @rb]; 
— WindowJnitiaUzeU is called by StarWindowShell Impls. 
body: window.Handle » starwindowSheii.CreateBody [ 
sws: shell, 

box: [[0,0],bodyWindowOims], 
repaintProc: Redisplay, 
bodyNotifyProc: NotifyProc ]; 



starWindowSheii.SetReguiarCommands [shell, myMenu]; 
starWindowSheii.SetPreferredDims [shell, bodyWindowOims]; 
starWindowSh«ii.SetPreferredPlace [shell, [200, 200]]; 
StarWindowShelLPush [shell]; 

}; 

NotifyProc: Tip.NotifyProc « { 

data: Oata 4-LocalFind(window]; 
place: window.Piace; 

FOR input: TiP.Results<- results, input.next UNTIL input « nil do 
WITH z: input select from 
coords ■ > place z.piace; 
atom ■ > SELECT z.a from 
pointUp « > { 

box: CARDINAL 4- ResoiveToBox [place]; 
IF Adjacent [data.empty, box] then { 

window.lnvalidateBox [window, boxes(data.empty]]; 

window.lnvalidateBox [window, boxes[box]]; 

SwapBox With Empty [data, box]; 
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Window. Vaiidate(window]; 
}; 

>; 

enocase; 
enocase; 



Redisplay: proc [window: window.Handie] « { 

— This is the body window's dispiay procedure. 
data: Data <~ LocalFind[window]; 

vertical: window.Dims [2, boxSize*grid]; 
horizontal: window.Oims [boxSize^grid, 2]; 
place: window.Place ^ (0,0]; 

— Display the 15 numbers 
FOR 1: CARDINAL IN [0..max) DO 

value: cardinal <-data.values(i]; 

oispiay.Bitmap [window, boxes[i]« [@bitmaps[value],0,0], boxSize]; 

ENDLOOP; 

— Dispiay the vertical lines 

FOR i: CARDINAL IN [0..grid -i- 2) DO 

Dispiay. Black [window, [place,vertical]]; 

place.x 4~ piace.x boxSize; 

enoloop; 
" Dispiay the horizontal lines 
place <~ [0,0]; 

FOR i: CARDINAL IN [0..gnd * 2) DO 

Dispiay.Black [window, [piace,horizontai]]; 
piace.y ^ place.y * boxSize; 

ENDLOOP; 

}; 

Init: PROC ■ { 

rb: xstring.ReaderBody <-xstring.FromSTRING("15 Puzzle"L]; 
StarOesi(top.AddltemToAttenti on Wi ndowMenu [ 
McnuData.Createltem [ 

zone: Heap.systemZone, 

name: @rb, 

proc: MenuProc] ]; 
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51.4 Index of Interface Items 



Item Page 

BitmapPlace: procedure 5 
BitmapPlaceToWindowAndPlace: procedure 5 

Box: TYPE 4 

BoxesAreOisjoint: procedure 4 

BoxHandle: type 4 

Clarity: type 10 

Create: procedure 6 

Dims: type 4 

DispiayProc: type 5 

EntireBox: procedure 7 

EnumeratelnvalidBoxes: procedure 10 

EnumerateT-ee: procedure 8 

Error: error 1 1 

ErrorCode: TYPE 11 

Float: procedure 12 

FtoatProc: PROCEDURE 12 

Free:pROCEOJRE 6 

FreeBadPhosphorList: PROCEDURE 11 

FreeTree: PROCEDURE 6 

GetBitmapUnder: procedure 12 

GetBox: procedure 7 

GetChild: procedure 7 

GetClearingRequired: procedure 6 

GetOisplayProc: procedure 6 

GetPane: procedure 7 

GetParent: procedure 6 

GetSibiing: procedure 6 

Gravity: type 9 

Handle: type 3 

Initialize: procedure 5 

InitializeWindow: procedure 5 

InsertlntoTree: procedure 8 

IntersectBoxes: procedure 4 

InvalldateBox: procedure 10 



Item Page 

IsBitmapUnderVariant: procedure. 12 

IsCookieVariant: procedure 7 

IsColorVariant: procedure 7 

IsOescendantOf Root: procedure 8 

IsPlacelnBox: procedure 5 

MinusLandBitmapUnder: type 4 

MinusLandColor: type 4 

MinusLandCookieCutter: type 4 

MouseTransf ormerProc: TYPE 12 

New: procedure s 

nullBox: Box 4 

Object: type 4 

ObscuredBySibiing: procedure 8 

Place: type 4 

RemoveFromTree: procedure 8 

Root: PROCEDURE 4 

rootWindow: variable 4 

SetBitmapUnder: PROCEDURE 12 

SetChild: procedure 8 

SetClearingRequired: procedure 6 

SetDisplayProc: procedure 6 

SetParent: procedure 8 

SetSibling: procedure 8 

Slide: procedure 9 

SlideAndSize: procedure 9 

SlideAndSlzeAndStack: procedure 9 

SlideAndStack: procedure 9 

Siidelconicaliy: procedure 10 

Stack: procedure 9 

TrimBoxStickouts: PROCEDURE 11 

UnderChangedProc: TYPE 12 

Validate: procedure io 

ValidateTree: procedure 10 

WordsForBitmapUnder: procedure 12 
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52.1 Overview 

The XChar interface is part of a string package that supports the Xerox Character Code 
Standard, referred to in this document as the "standard." XChar defines the basic 
character type and some operations on it. 

The standard defines 16-bit characters, which would permit up to 65,536 distinct 
characters. Reserving control character space reduces them to 35,532. It is convenient to 
partition the character code range into 256 blocks of 256 codes each. Each block is called a 
character set This approach allows a convenient run-encoding scheme. 

All the character sets currently defined are enumerated in XCharSets. 

52.2 Interface Items 

52.2.1 Character Representation 
Character: type » word; 
Character is a 16-bit character. 

Fine point: Currently only 16-bit characters are defined by the standard, but larger characters are not precluded. 
If the standard is extended to include more bits per character, the type Character will be redefined. 

CharRep:TYPE ■ machine dependent record (set, code: Environment.Byte]; 

CharRep is a type that defines the representation of a character as character set and code. 
The operations Code, Make, and Set should be used instead of this type. 

Code: procedure [c: Character] returns [code: Environment. Byte] ; 

Code returns the code within a character set of the character parameter. 

Make: procedure [set, code: Environment.Byte] RETURNS [Character]; 



52-1 



52 XChar 



Make constructs a character, given a character set and a code within the character set. 

Set: PROCEDURE [c: Character] returns [set: Environment.Byte] ; 

Set returns the character set of the character parameter. 

null: Character ■ 0; 

not: Character ■ 177777B; 

not is a value that may be used by operations that return a character to signify that no 
characters remain. 

32.2.2 JoinDirection and StreakNature 

JoinDirection: type ■ (nextCharToLeft, nextCharloRight}; 

JoinDirection specifies whether a character goes lefb to right or right to left. 

GetloinOirection: procedure [Character] returns [JoinDirection]; 

GetloinDirection returns the join direction for a character, given its set and code within its 
set. 

ArabicFirstRightToLeftCharCode: Environm«nt.Byte ■ 60B; 
ArabicFirstRightToLeftCharCode is used by GetloinDirection. 
StreakNature: type ■ {leftToRight, rightToLeft}; 
GetStreakNature: procedure [Character] returns [StreakNature]; 

Returns a characters StreakNature (see SimpleTextoisplay.StreakSuccession). 

32.2.3 Case 

Decase: procedure [c: Character] returns [Character]; 

Decase is a case-stripping operation. It returns c with all case information removed. This 
is useful when comparing characters with case ignored. Only characters in character sets 
zero (Latin), 46(Greek), and 47(Cyrillic) are affected. 

Lowercase: procedure [c: Character] returns [Character]; 

Lowercase returns the lowercase representation of the character c. Only characters in 
character set zero (Latin), 46 (Greek), and 47 (Cyrillic) are affected. 

Uppercase: procedure [c: Character] returns [Character]; 

Uppercase returns the uppercase representation of the character c. Only characters in 
character set zero (Latin), 46 (Greek), and 47 (Cyrillic) are affected. 
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52.3 Usage/Examples 

The following two examples create specific characters. xchar.Make is also useful if the 
character set and code are not known at compile time, but are known at run time. 

52.3.1 Creating an ASCII Character 

The following example creates an ASCII CR character. 

c: xchar.Character 4-xchar.Make(set: xcharSets.Sets.iatin.ORD, code:L0OPHOLE[Ascii.CR]]; 

52.3.2 Creating a Greek Character 

The following example creates an a from the Greek character set. 

c: xchar.Character 4-xchar.Mai<e[set:xcharSets.Sets.greek.0RD, code: 
xcharSet46.Codes46.iower Al pha.ORo] ; 
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52.4 Index of Interface Items 

Item Page 

ArabicFirstRightToLeftCharCode: type 2 

Character: type 1 

CharRep: type 1 

Code: procedure 1 

Decase: procedure 2 

GetioinOirection: procedure 2 

GetStreakNature: procedure 2 

JoinDirection: type 2 

Lowercase: procedure 2 

Make: procedure 1 

null: TYPE 2 

not: TYPE 2 

Set: PROCEDURE 2 

StreakNature: type 2 

Uppercase: procedure 2 
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53.1 Overview 

XCharSets enumerates the character sets defined in the Xerox Character Code Standard. 
This chapter also describes a collection of interfaces that enumerate the character codes of 
several common character sets. This collection of interfaces is XCharSetNNN. 

53.2 Interface Items 
53.2.1 Sets 

Sets: TYPE a MACHINE DEPENDENT { 

latin(O), firstUnused1(1), lastUnused1(40B), jisSymbol1(41B), jisSymbol2(42Bh 
extendeclLatin(43B), hrragana(44B), katakana(45B). greek(46B), cyrillic(47B), 
firstUserKanji1(50B), lastUserKanji1(57B),firstLevei1Kanji(60B), 
lastLevel1Kanji(117B),fjrstLevel2Kanjl(120B), lastLevel2Kanji(163B), jSymbol3(164B), 
firstUserKanji2(165BK lastUserKanji2(176B), firstUnused2(177B), lastUnused2(240B), 
firstReserved1(241B), lastReserved1(337B), arabic(340B), hebrew(341 B), 
firstReserved2(342B), lastReserved2(355B), generaiSymbois2(356B), 
generaiSynibois1(357B), firstRendering(360B), iastRendering(375B), 
userOefined(3766), selectCode(377B)}; 

Sets enumerates the character sets. Specific character sets have values defined, such as 
Latin and Hiragana. Character set families such as Kanji and unused or reserved portions 
of the character set enumeration are specified by first and last values; for example, 
firstUserKanjil and lastUserKanjh. 

For those eleven character sets whose codes are specified in the standard, an interface has 
been defined that contains an enumerated type enumerating the codes within the 
character set and a Make procedure that makes a character, given a code literal. 

For example, the interface XCharSet356 has the following definitions: 

Make: procedure [code: Codes356] returns [Character]; 
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Codes3S6: TYPE > machine dependent ( 

thickSpace(41 B), fourEmSpace(42B), hairSpace(43B), punctuationSpace(44B), 
decimalPoint(56B), absoluteValue(174B), simiiarTo(176B), escape(377B)}; 

53.2.2 Enumeration of Character Sets 

Table 53.1 enumerates the eleven character sets whose codes are specified in the standard, 
the interface in which they are contained, and the enumerated type name for that 
interface. 



Character Set 


Interface 


Enumerated Type 


Latin 


XCharSetO 


CodesO 


jisSymboll 


XCharSet41 


Codes41 


jisSymbol2 


XCharSet42 


Codes42 


extended Latin 


XCharSet43 


Codes43 


Hiragana 


XCharSet44 


Codes44 


Katakana 


XCharSet45 


Codes45 


Greek 


XCharSet46 


Codes46 


Cyrillic 


XCharSet47 


Codes47 


jSymbolB 


XCharSet164 


Codes 164 


arable 


XCharSet340 


Codes340 


Hebrew 


XCharSet341 


Codes341 


generalSymbols2 


XCharSet356 


Codes356 


generaiSymbolsl 


XCharSet357 


Codes357 


firstRendering 


XCharSetSeO 


Codes360 


accented Latin 


XCharSet361 


Codes36 1 



Table 53. 1 : Standard Character Sets 

53.3 Usage/Examples 

53.3.1 Creating a Greek Character 

The following example shows two ways to create an a from the Greek character set. 

c: xchar.Character 4-xchar.Make[set:xcharSets.Sets.greek.0RD, code: 
xcharSet46.Codes46.lowerAlpha.ORD]; 

C: xchar.Character <- XCharSet46.Make[code: xcharSet46.Codes46.lowerAi pha] : ^ll 
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Item Page 
Sets: TYPE 1 
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54.1 Overview 

This interface assigns the global handlejind message keys for all the messages the system 
requires for system templates (such as time and date formatting, numbers, and so forth.). 
The XMessage interface deals with system messages; it must be understood before using 
this interface. 

54.2 Interface Items 

54.2.1 Obtaining Message Handle 

GetHandle: procedure returns [h: xMessage.Handle]; 

This procedure returns a handle for system-required messages that have already been 
initialized and allocated, and registered by the XComSoftMessage implementation. 

54.2.2 Message Keys 

Keys: type » machine dependent { 

time(O), date(1), dateAndTime(2), am(3K pni(4), january(5), february(6), march(7), 
april(8), may(9), june(IO), july(ll), august(12), september(13), october(14), 
november(15), december(16). monday(17), tuesday(18), wednesday(1 9), 
thursday<20), friday(21), saturday(22), sunday(23), decimalSeparator(24), 
thousandsSeparator(25)}; 

time, date, and dateAndlime are available through the XTime interface; they may be 
used as templates in calls to XTime.ParseReader or XTime.Append. 

Months: type » Keys [january..december]; 

DaysOfWeek: type a Keys [monday..sunday]; 
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54.3 Usage/Examples 

OPEN XCSM: XComSoftMessage; 

systemMsgs: xMessage.Handle ^-xcsM.GetHandle []; 
mondayString: xstring.Reader <- XMessage.Get [ 
systemMsgs, xcsM.DaysOfWeek.monday.ORO]; 
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54.4 Index of Interface Items 



Item Page 

GetHandle: procedure 1 

Keys: type 1 

Months: type 1 

OaysOfWeek: type 1 



54-3 



54 XComSoftMessage 



54-4 



XFormat 



56.1 Overview 

The XFormat package provides procedures for formatting various types into 
xstring.Readers. The procedures require the client to supply an output procedure and a 
piece of data to be formatted. Where appropriate, a format specification is also required. 

55.1.1 Major Data Structures 

The major data structure is the Handle, which points to an object containing a FormatProc, 
an xstring.Context, and some ClientData. All the formatting operations take a handle as 
the destination of the formatted character string. The FormatProc is the main component 
of an Object. It should pass the characters of its reader parameter to the output sink it 
implements and update the object's context to reflect the context of the last character of 
the reader parameter. 

The other major data structure is the NumberFormat, which defines how numbers are to 
be converted to text strings. It includes the base of the number, the number of columns the 
text string should contain, whether to treat the number as signed or unsigned, and 
whether to fill leading columns with zeros or spaces. 

A FormatProc is the destination of all output from the format routines. It is the main 
component of an Object. It passes the characters of r to the appropriate sink and updates 
h. context to reflect the context of the last character of r. 

55.1.2 Operations 

There are two major classes of operations in XFormat. The first class is used to format 
various data types and pass them to a format procedure. These operations contain simple 
text operations such as Blanks, Reader, and String; numeric operations such as Decimal 
and Number; network- related operations such as NetworkAddress and HostNumber; 
and some compatibility routines such as NSString. All these operations direct their output 
to the format procedure in their handle parameter. If this parameter is defaulted, it is 
directed to the default output sink. 
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The second class of operations provide built-in format procedures that direct their output 
to the following well-known data types: xstring.Wrlter, stream.Handie, TTY.Handle.and 
NSString.String. 

55.2 Interface Items 



55.2.1 Handles and Objects 

Handle: TYPE « long pointer to Object; 

Object: type « record [ 
proc: FormatProc, 

context: xstringXontext <~ xstring.vanillaContext, 
data: ClientOata 4-nil]; 

FormatProciTYPE a procedure [r: xstrmg.Reader. h: Handle]; 

CllentOata: type ■ long pointer; 

A Handle is a parameter to all the formatting operations. Its object encapsulates the 
output sink that is the destination of all formatted text. The proc field is called one or more 
times for each formatting operation; it should pass the characters of its reader parameter 
to the output sink it implements. The context field is used to hold the context of the last 
character sent to the format procedure. It should be updated by the format procedure. The 
data field allows client-specific information to be passed to the format procedure. 

55.2.2 Default Output Sink 

SetDefaultOutputSink: procedure [new: Object] returns {old: Object]; 

SetOefaultOutputSink sets the default object that is the default destination for all 
formatted output. For each of the formatting operations, if the handle parameter is nil, it 
is directed to the default output sink. The default output sink is initialized to an object 
that ignores all results. 

55.2.3 Text Operations 

Blanks: procedure [h: Handle ^ NIL, n: cardinal <- 1]; 

Blanks calls on h.proc with readers that contain a total of n blanks, h.proc may be called 
more than once. 

Block: PROCEDURE [h: Handle «- NIL, block: Environinent.Block]; 

Block calls on h.proc with a reader that contains the characters in block. 

Char: procedure [h: Handle NIL, char: xstring.Character]; 

Char calls on h.proc with a reader that contains only the character char. 
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CR: PROCEDURE [h: Handle NIL, n: cardinal 4-1]; 

CR calls on h.proc with readers that contain a total of n carriage returns (15C). h.proc 
may be called more than once. 

Line: procedure [h: Handle *- NIL, r: xstring.Reader, n: cardinal <~ 1]; 

Line calls on h.proc with r and then readers that contain a total of n carriage returns 
(15C). h.proc may be called more than once. 

Reader: PROCEDURE [h: Handle NIL, r: xstring.Reader]; 

Reader calls on h.proc with r. 

ReaderBody: procedure [h: Handle <~ NIL, rb: xstring.Reader]; 

ReaderBody calls on h.proc with @rb. 

String: procedure [h: Handle *- NIL, s: long string]; 

String calls on h.proc with readers that contain the characters in s. 

55.2.4 Number Formats 

NumberFormat: type x record [base: [2..36] <~ 10, 

zerofiil: boolean «~ false, signed: boolean *- false, columns: [0..255] 0 ]; 

NumberFormat is used by the number-formatting procedures. The number is formatted in 
base base in a Aeld at least columns wide (zero means "use as many as needed"). If zerofiil 
is TRUE, the extra columns are filled with zeros; otherwise, spaces are used. If signed is true 
and the number is less than zero, a minus sign proceeds all output, e.xcept for columns that 
are filled with spaces. For bases greater than 10, the characters 'A,.'Z are used as digits. 

DecimalFormat: NumberFormat * [ 

base: 10, zerofiil: false, signed: true, columns: 0]; 

HexFormat: NumberFormat ■ [ 

base: 16, zerofiil: false, signed: false, columns: 0]; 

OctalFormat: NumberFormat ■ [ 

base: 8, zerofiil: false, signed: false, columns: 0]; 

UnsignedDecimalFormat: NumberFormat ■ [ 

base: 10, zerofiil: false, signed: false, columns: 0]; 

These are useful number format constants. The output fills as many columns as needed. 
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55.2.5 Numeric Operations 

Number: procedure [ 

h: Handle «- NIL, n: long unspecified, format: NumberFormat]; 

Number formats n to a string according to the number format formal The number is 
formatted in base base in a field at least columns wide (zero means "use as many as 
needed"). If zerofill is true, the extra columns are filled with zeros; otherwise, spaces are 
used. If signed is true and the number is less than zero, a minus sign preceeds ail output, 
except for columns that are filled with spaces. For bases greater than 10, the characters 
'A..'Z are used as digits, h.proc will be called several times with pieces of the output as 
they are generated. 

Decimal: procedure [h: Handle NIL, n: long integer]; 

Decimal converts n to signed base 10. It is equivalent to Number[h, n, DecimalFormatj. 
Hex: procedure [h: Handle NIL, n: long cardinal]; 

Hex converts n to signed base 16. It is equivalent to Number[h, n, HexFormat]. 
Octal: procedure [h: Handle <~ NIL, n: long unspecified]; 

Octal convert n to base 8. When n is greater than 7, the character 'B is appended. It is 
equivalent to Number[h, n, OctalFormat]; if n > 7 then Char[h, 'B.ord]. 

55.2.6 Built-in Sinks 

The XFormat interface provides several built-in format procedures that know how to send 
output to particular destinations. For each of the four known types of destinations 
(xStrmg.Writer, Stream. Handle, TTY. Handle, and NSString.String), there are both the format 
procedure as well as an operation that returns an object initialized with the appropriate 
format procedure and destination data. Both the format procedures and the object 
operations may raise the error Error[nilOata] if the expected data is nil. 

NSStringProc: FormatProc; 

NSStringObject: procedure [s: long pointer to NSString.String] returns [Object]; 

NSStringProc appends the reader to an NSString.String. It expects h.data to be a long pointer 
to NSString.String. NSStringObject constructs an object whose proc is NSStringProc and 
whose data is s. 

StreamProc: FormatProc; 

StreamObject: procedure [sH: stream.Handle] returns [Object]; 

StreamProc puts the bytes of the reader to a stream.Handle. It expects h.data to be a 
Stream.Handle. StreamObject constructs an object whose proc is StreamProc and whose jfHi 
data is sH. 
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TTYProc: FormatProc; 

TTYObject: procedure [h: TTY.Handle] returns [Object]; 

TTYProc puts the bytes of the reader to a TTY.Handle. It expects h.data to be a TTY.Handle. 
TTYObject constructs an object whose proc is TTYProc and whose data is h. 

WriterProc: FormatProc; 

WriterObject: procedure [w: XStrlng.Writer] returns [Object]; 

WriterProc appends the reader to a xstring.Writer. It expects h.data to be a xstring.Writer. 
WriterObject constructs an object whose proc is WriterProc and whose data is w. 

35.2.7 Date Operation 

OateFormat: TYPE ■ {dateOnly,timeOniy,dateAndTime}; 

OateFormat allows the user to specify which template from XTime is used when the date is 
to be formatted by the procedure Date. 

Date: procedure [ 

h: Handle NIL, time: System.GreenwichMeanTime <-Sy$tem.gmtEpoch, 
format: OateFormat <-dateAndTi me]; 

Date converts time to a string by calling XTime.Append, using format to specify which 
template to use. h.proc is then called. If time is defaulted, the current time is used. 

35.2.8 Network Data Operations 

NetFormat: type « {octal, hex, productSoftware}; 

NetFormat is used by the procedures that format network addresses, octal converts the 
number to octal, hex converts to hex, and productSoftware converts the item to a decimal 
number and then inserts a every three characters, starting from the right. An example 
of a number in product software format is 4-294-967-295. 

HostNumber: procedure [ 

h: Handle <~ NIL, hostNumber: System.HostNumber, format: NetFormat]; 

HostNumber calls on h.proc with a reader that contains hostNumber formatted as defined 
by format. 

Network Address: procedure 

h: Handle <— NIL. networkAddress: SysteiK.NetworkAddress, format: NetFormat]; 

Network Address calls on h.proc with a reader that contains networkAddress with the 
form network-namber#host'number#socket-number, where the format of the various 
components isdetermined by format. 
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NetworkNumber: procedure [ 

h: Handle «- NIL, network Number: System.NetworkNumber, format: NetForma.t]; 

NetworkNumber calls on h.proc with a reader that contains networkNumber formatted 
as defined by format. 

SocketNumber: procedure [ 

h: Handle *- NIL, socketNumber: System.SocketNumber, format: NetFormat]; 

SocketNumber calls on h.proc with a reader that contains socketNumber formatted as 
defined by format. 

55.2.9 NSString Operations 

NSChar: procedure [h: Handle <- NIL, char: NSString.Character]; 

NSChar calls on h.proc with a reader that contains the character char. 

NSLine: procedure [h: Handle *- NIL, s: NSString.String, n: cardinal 1]; 

NSLine calls on h.proc with a reader that contains the characters in s and then calls on 
readers that contain a total of n carriage returns (15C). h.proc may be called more than 
once. 

NSString: procedure [h: Handle <- NIL, s: NSString.String]; 

NSString calls on h.proc with a reader that contains the characters in s. 

55.2.10 Errors 

Error: error [code: ErrorCode] ; 

ErrorCode: type = {InvalidFormat, nilData}; 

invaiidFormat An invalid operation has been attempted 

nilData h.data was nil, but the format procedures wanted valid data. 

55.3 Usage/Examples 

55.3.1 Using Built-in Sinks 

The XFormat interface allows clients to convert data types to their textual representation. 
By using the built-in sinks, clients can put this text into streams, tty.handle, and append 
to writers. In particular, although the XString interface does not include any append 
number operations, XFormat may be used for this task. 

AppendNumber: procedure [ 

w: xstring.Writer, n: long integer, format: xFormat.NumberFormat] « { 
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xfo: XFormat.Object <- xFormat.WriterOb]ect(wl; 
XFormat.Numberfh: @xfo, n: n, format: format]}; 

55.3.2 Creating New Format Procedures 

While XFormat provides some useful output sinks, clients may wish to build new sinks. 
The following example hypothesizes a log window that can display text in a window and 
allows appending of text to the end. 

LogWindow: definitions ■ { 
Create: procedure (w: window.Handle, file: NSFUe.Handle]; 
Destroy: procedure [w: window.Handle]; 

LogReader: procedure [w: window.Handle, r: xstring. Reader]; 
Info: procedure [w: window.Handle] returns! 

file: NSFiie.Handle, nChars: long integer. endContext: xstring-Contextj; 

LogFormatProc: xFormat-FormatProc; 

LogFormatObject: procedure [w: window.Handle] returns [object: XFormat.Object] 

ErrorCode: type « {notALogWindow}; 

Error: Error [code: ErrorCode]; 

}.. 

LogWindowimpi: program « { 

Create: PUBLIC procedure [w: Window.Handle, file: NSFiie.Handle] ■ {...}; 
Destroy: PUBLicPROCEDUR£[w: Window.Handle] * {...}; 

LogReader: public procedure [w: window.Handle, r: xstring.Reader] » {...}; 
Info: public procedure [w: window.Handle] returns [ 

file: NSFiie.Handle, nChars: long integer. endContext: xstring.Context] « {...}; 

LogFormatProc: PUBLIC XFormat. FormatProc » { 
w: Window.Handle ■ h.data; 
iFw ■ NIL then error XFormat.Error[nilData]; 
LogReader[w: w, r: r]; 
h.context Inf o[w].endContext}; 

LogFormatObject: public procedure [ 

w: Window.Handle] returns [object: XFormat.Object] « { 
iFw ■ nil THEN error XFormat.Error[nilData]; 

RETURN[[proc: LogFormatProc, context: I nfo[w]. endContext, data: w]]}; 

}.. 

The bulk of the work is done in the LogReader procedure. It is assumed that the log 
window keeps track of the context of the end of the log so that it will add the necessary 
character set shift information when a reader that begins with a different character set is 
logged. If the log window did not take care of this, the format procedure would have to set 
it itself, as the stream format procedure example below shows. 
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StreamProc: PUBLIC xFormat.FormatProc ■ { 
stream: stream.Handle » h.data; 
starts With377B: boolean; 
c: xstring.Context; 

IF stream • nil then error XFormat.Error[niiData]; 

[context: c, starts With377B: startsWith377B] 4-xstring.Readerinfo{r]; 

SELECT true FROM 

startsWith377B « > null; 
csuffixSize a 2 ■ > 

IF h.context.suffixSize ■ 1 then { 

stream.PutByte(377B]; stream.PutByte[377Bl; stream.PutByte[01}; 
h.context.suffixSize « 2, cprefix # h.context.prefix a > { 

stream.PutByte[377B]; stream.PutByte(c.prefixJ}; 
endcase; 

stream.PutBlock(block: xstring.Block[r]]; 
h.context <-xstring.ComputeEndContext(r]}; 
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55.4 Index of Interface Items 

Item Page 

Blanks: procedure 2 

Block: PROCEDURE 2 

Char: procedure 2 

ClientData: type 2 

CR: procedure 3 

Date: procedure 5 

DateFormat: type 5 

Decimal: procedure 4 

DecimalFormat: NumberFormat 3 

Error: error 6 

ErrorCode: type 6 

FormatProc: type 2 

Handle: type 2 

Hex: procedure 4 

HexFormat: NumberFormat 3 

HostNumber: procedure 5 

Line: procedure 3 

NetFormat: type 5 

NetworkAddress: procedure 5 

NetworkNumber: PROCEDURE 6 

NSChar: procedure . 6 

NSLine: procedure 6 

NSString: procedure 6 

NSStringObject: procedure 4 

NSStrlngProc: FormatProc 4 

Number: procedure 4 

NumberFormat: type 3 

Object: type 2 

Octal: procedure 4 

OctalFormat: NumberFormat 3 

Reader: procedure 3 

ReaderBody: procedure 3 

SetOefaultOutputSink: procedure 2 

SocketNumber: procedure 6 

StreamObject: procedure 4 

StreamProc: FormatProc 4 

String: procedure 3 

TTYObject: procedure 5 

TTYProc: FormatProc 5 

UnsignedDecimalFormat: NumberFormat 3 

WriterObject: procedure 5 

WriterProc: FormatProc 5 
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56.1 Overview 

XLReai is a decimal real package that supports manipulation of real numbers with greater 
precision than MesaREAis. 

56.2 Interface Items 

56.2.1 Representation 

Numbers are maintained as 13 decimal digits of signed mantissa with a 10-bit exponent 
(-512 to 511). All routines maintain the normalized numbers (that is, the first digit is 
non-zero). The assumed decimal point is after the first digit. Numbers are stored as 
opaque objects occupying four words (64 bits). 

Digit: type * [0..91; 
Number: type [4]; 

Bits: TYPE 3 ARRAY [0..4) OF CARDINAL; 

ValidExponent: type = [-512..5111; 

Digits: type » packed array [Caccuracy) of Digit; 

accuracy: NATURAL » 13; 

56.2.2 Conversion. 

XLReal provides routines to convert numbers to and from other representations such as 
LONG integers and reals as well as routines to look at pieces of numbers. 

NumberToPair: procedure [ 

n: Number, digits: [1.. accuracy]] returns [negative: boolean, exp: integer, mantissa: 
Digits]; 

PairToNumber: procedure[ 

negative: boolean, exp:iNTE6ER, mantissa: Digits] returns [n: Number]; 
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In PairToNumber and NumberToPair, the decimal point, is between mantissa[01 and jill 
niantissa[l]. NumberToPair rounds n so that mantissa contains digits significant digits. 
All other digits are zero. NumberToPair may raise Error[notANumber]. PairToNumber 
may raise Error[underf low]. 

IntegerPart, FractionPart: procedure [Number] returns [Number]; 

integerPart and FractionPart may raise Error[notANumber]. FractionPart may also, raise 
Error[overflow]. 

Fix:PR0CEDURE [Number] returns [long integer]; 
Float: procedure [long integer] returns [Number]; 

Fix may raise Error[notANumber] and Error[overflow]. Fix rounds (as opposed to 
truncate). 

ToREAL:proceoure [number: Number] returns [real]; 

ToREAL converts number to a real. If Abs[number] is greater than the largest real 
(3.40282347E38) it will return Real.Pluslnfinity or Real.Minuslnfinity, depending on 
number's sign. If it is less than the smallest real ( 1. 17549435E-38) it returns 
Reai.PlusZero or Reai.MlnusZero, depending on number's sign. Some precision may be lost 
because a number's precision is greater than a real's precision. ToREAL may raise 

ErrOr[nOtANumber] . Fine point: This procedure is currently exported through XLRealX.. jIBii 

FromREAL: procedure [real: real] returns [Number]; 

FromREAL converts real to a Number. If real is Real.Pluslnfinity or Real.Minuslnfinity, 
FromREAL returns 9.999999999999E511 or -9.999999999999E511 depending on real's 
sign. If real is not a number, FromREAL returns MakeSpecial[0];. Fine point: This procedure is 
currently exported through XLRaalX. 

56.2.3 Input/Output 

The input and output routines convert numbers to and from a stream of characters. 
ReaderToNumber: pROCEDURE[r: xstring. Reader] returns [Number]; 

ReaderToNumber converts r into a number. The number may have leading and trailing 
white space (spaces, tabs, and returns). It may raise Error[overfiow] if the number is too 
big or Error[notANumber] if the reader contains invalid characters. 

ReadNumber: procedure [ 
get: proc returns [xchar.Character]« putback: proc [xchar.Character]] returns [Number]; 

ReadNumber converts the stream of characters from get into a number. Any character 
other than white space, ' + , '-, 'E, 'e, '0-'9, or the decimal separator causes conversion to 
terminate and putback is called with that character. It may raise Error[overf low]. 

FormatReal: procedure [h: xFormat.Handle *- NIL, r: Number, width: natural]; 
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FormatReal formats r into a field width elements wide and passes the resulting text to h. If 
the number does not fit, the field is filled with *> characters, h.proc may be called more 
than once. 

PictureReai: procedure [ 

h: XFormat.Handie ^ NIL, r: Number, template: xstring.Reader]; 

PictureReai is not implemented. Use FormatNumber for control over output. 

NumberFormat: type ■ record [ 
columns: CoiumnCount *- 0, 
type: FormatType<~ fixed, 
fill: Fill ^ [none, 0], 

digitSpec: select choice: DigitChoice from 
fractions > > [fractions: DigitCount], 
digits a > [digits: DigitCount], 
ENOCASE 4~digits[0]]; 

CoiumnCount: type « [0..256); 

FormatType: type ■ {fixed, scientific, automatic}; 

Fill: TYPE m record [type: FillType, nChars: CoiumnCount]; 

FillType: type ■ {zero, blank, none}; 

DigitCount: type ■ [0..accuracy]; 

DigitChoice: type ■ {fractions, digits}; 

NumberFormat is used by FormatNumber to allow precise control over the formatted 
number, columns specifies the number of columns required; zero means use as many as 
needed, type specifies whether the number is formated in fixed notation (fixed), scientific 
notation (scientific), or fixed if it will fit in the number of columns or scientific; otherwise, 
(automatic), fill specifies the type and number of characters of additional fill that is 
required before the number, zero and blank mean use zeros or blanks, respectively, as the 
fill characters, while none means use not fill. digitSpec allows the number of digits or 
fractions to be specified. fractions[nl means have n digits to the right of the decimal. 
digits[n] means have n significant digits in the number, except that digits[0] means have 
any number of digits in the number. 

If type ■ automatic and columns ■ 0, then f.digits determines whether the number will be 
fixed or scientific. This allows a client to say "I want f.digits of significant digits and you 
figure out whether it should be fixed or scientific." Using type a automatic and 
columns#0 means that FormatNumber uses columns to determine whether the number is 
fixed or scientific. Often the client wants to specify significant digits rather than number 
of columns, especially because the number of columns will vary, depending on the format 
and the value of the number. 

FormatNumber: proc[ 

h: XFormat.Handle <- nil, r: Number, 

format: NumberFormat <-defaultFormat, signallfWontFit: boolean false]; 
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defaultFormat: NumberFormat ■ [ 

columns: 0, type: fixed, fill: [none, 0], digitSpec: digits[0]]; 

WontFit: SIGNAL; 

FormatNumber formats r according to format. If format specifies a number of columns, 
and if the formatted number will not fit and signallfWontFit is true, the signal WontFit is 
raised, If it is resumed or if the number won't fit and signallfWontFit is false, 
format.columns *> is passed to h.proc. If the number of columns or digit specification 
restricts the number of significant digits presented, the number of significant digits is 
reduced by rounding. If h is defaulted, output goes to the default output sink. (See the 
XFormat chapter for more details.) The default format specifies fixed notation in as many 
columns as necessary with no additional fill. If r is negative, the negative sign appears 
before zero fill and after blank fill, h.proc may be called more than once. Fine point: Thi.s 
procedure is currently exported through XLRealX. 

56.2.4 Comparison 

Comparison: TYPE a {less, equal, greater}; 

Compare: procedure [a, b: Number] returns [Comparison]; 

Less, LessEq, Equal, GreaterEq, Greater, NotEq: procedure [ 
a, b: Number] returns [boolean]; 

Any of the compare op>erations may raise Error[notAN umber]. 

36.2.5 Operations 

Add, Subtract, Multiply, Divide, Remainder: procedure [ 
a, b: Number]RETURNS [Number]; 

Add, Multiply, Divide and Remainder may raise Error[notANumber] and Error[overfiow] 
Divide may also raise Error[divideByZero]. 

Exp: procedure [Number] returns [Number]; 

Exp computes the results by continued fractions. Exp may raise Error[underflaw], 
Error[notANumber] and Error(overfiow]. 

Log: procedure [base, arg: Number] returns [Number]; 

Log computes the logarithm to the base base of arg by Ln(arg)/Ln(base). Log may raise 
Error[overflow], Error[invaiidOperation], and Error[notANumber]. 

Ln: procedure [Number] returns [Number]; 

Ln may raise Error[notANumber] , Error[overflow] , and Error[invalidOperation]. 
Power: procedure [base, exponent: Number] returns [Number]; 
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Power calculates base to the exponent power by e(exponent*Ln<base)). Power may raise 
Error[notANumber] and Error[overfiow]. 

Root: PROCEDURE [index, arg: Number] returns [Number];- 

Root calculates the index root of arg by e(Ln(arg)/index). Root may raise Errorfoverflow], 
Error[notANumber], and Error[underflow]. 

SqRt: PROCEDURE [Number] returns [Number]; 

SqRt calculates the square root of the input value by Newton's iteration. SqRt may raise 
Error[notANumber] and Error[invaiidOperation]. 

Abs, Negative, Double, Half: procedure [Number] returns [Number] ; 

Abs, Negative, Double and Half may raise Error[notANumber] Double may also raise 
Error[overflow]. 

Cos: procedure [radians: Number] returns [cos: Number]; 
Sin: procedure [radians: Number] returns [sin: Number]; 
Tan: procedure [radians: Number] returns [tan: Number]; 

Computes the trigonometric function by polynomial. Angles are measured in radians 
measured counterclockwise from the positive x axis about the origin [0, Oj. Sin, Cos and 
Tan may raise Error[notANumber] and Error[in validOperation] (if 
radians.exponent> 11). Tan may also raise Error[overflow]. 

ArcCos PROCEDURE [x: Number] returns [radians: Number]; 
ArcSin procedure [x: Number] returns [radians: Number]; 
ArcTan procedure [x: Number] returns [radians: Number]; 

Transcendental functions have an accuracy of about 1 X 10_^^ ArcCos, ArcSin and ArcTan 
may raise Error(notANumber]. ArcSin may also raise Error[invalidOperation] (if x NOT 
IN 

36.2.6 Special Numbers 

A client can create special numbers that cause the Error[notANumber] to be raised if used 
in any arithmetic operation. 

Special! ndex: type a natural; 

MakeSpecial: procedure [index: Speciallndex] returns [Number]; 
isSpecial: procedure [Number] returns [yes: boolean, index: Speciallndex]; 

56.2.7 Errors 

Error: error [code: ErrorCode]; 

ErrorCode: type » {bug, divideByZero, invalidOperation, notANumber, overflow, 
underflow, unimplemented}; 
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notANumber The number passed in is a special number. jllll 

56.2.8 Special Constants 

zero: Number ■ loophole[ Bits(0, 0, 0] ]; 

Pi: PROCEDURE RETURNS [Number]; 
E: PROCEDURE RETURNS [Number]; 

56.3 Usage/Examples 

36.3.1 Special Numbers 

—Make the special number 

special :xLReal.Number <- xLReal.MakeSpecial[1]; 

•'Do some computations with Numbers 

"If a problem occurs during computation, assign 
n«~ special 



[] <-XLReal.Ln[n]; 

—Ifn = special this call to XLReal.Ln will raise Error[notANumber] 

56.3.2 Times of Common Operations 

For the four arithmetic operations, typical timings (in microseconds) compared with the 
current Common Software 32-bit IEEE floating-point package (with no microcode assist) 
are: 





XLReal 


REAL 


Add or Subtract 


500 


800 


Multiply 


800 


1000 


Divide 


1500 


1900 
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57.1 Overview 

The XMessage interface supports the multilingual requirements of systems requiring 
that the -text to be displayed to the user be separable from the code and algorithms that 
utilize it. This allows workstation applications to define messages and developers and 
translators to supply the international representations of the text. The XMessage 
interface defines the message transfer mechanism necessary for applications to define 
application-specific messages, register them with the system, and access them. 

The XMessage interface is part of the entire message machinery that provides 
multilingual text. Applications must be written to rely on messages for their text. A tool 
translates messages and produces a file containing the translated version of the messages. 

57.1.1 Message Usage 

Applications define collection of messages and refer to them by using a Handle. A unique 
key relative to that handle represents each message. To get the text of a message, the 
client calls Get or GetList. During development of applications, message handles are 
obtained by calling AilocateMessages and RegisterMessages. When the development is 
completed and a message file is generated, message handles are obtained by calling 
MessagesFromFile or MessagesFromReference. 

Applications should be broken into three parts: the main code of the application that uses 
the messages, the code that defines and initializes the messages, and the code that gets 
message handles from the message file. 

,57.1.2 Message Composition and Templates 

Frequently, text presented to the user should include items like names and sizes of objects, 
dates,and so forth. When defining such messages, it is best to define a single message 
template that allows certain fields to be filled in with this information. The piecemeal 
approach to constructing a understandable sentence normally does not work when the 
message is translated to a different language. 
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Templates are messages that will have additional text merged into them. The fields in jflik 
templates are defined by numbers enclosed in angle brackets if the template contains 
multiple fields, or simply by angle brackets, if there is only one field. 

57.2 Interface Items 

37.2.1 Handles 

Handle: TYPE ■ long pointer to Object; 
Object: type; 

A Handle represents a collection of messages. It is normally associated with a particular 
application. It is obtained from the AliocateMessages operation and is a parameter of 
most operations. 

37.2.2 Getting Messages 

Get: procedure [h: Handle, msgKey: MsgKey] returns [msg: xstring.ReaderBody]; 

Get returns the message corresponding to the given message key within the group of 
. messages specified by h. 

GetList: procedure [h: Handle, msgKeys: MsgKeyList, msgs: StringArray]; jgi^ 

MsgKeyList: type » long descriptor for array of MsgKey; 

StringArray: type ^ long descriptor for array of xstring.ReaderBody; 

GetList fills the array of reader bodies with the bodies of the messages whose keys are in 
the message key list. This procedure is equivalent to: 

FOR i IN [0..msgKeys.LENGTH) do msgs[i] <-Get[msgKeys[i]]; endloop. 

This procedure raises Error[invalidMsgKeyList] if msgKeys is nil, 
ErrorfinvalidStringArray] if msgs is nil, and Error[arrayMismatch] if the lengths of the two 
descriptors are not equal. 

37.2.3 Composing Messages 

ComposeToFormatHandle: procedure [ 

source: xstring.Reader, destination: xFormat.Handle, args: Stri rig Array]; 

Compose: procedure [ 

source: xstring.Reader, destination: xstnng. Writer, args: StringArray]; 

ComposeToFormatHandle and Compose compose a message by replacing the fields in 
source with the text in args. ComposeToFormatHandle uses an XFormat.Handle as the 
destination of the message, while Compose uses an xstring.Writer. A field is specified by a 
number enclosed in angle brackets. These operations may raise Error[invalidStringJ if 
source is empty and ErrorlnotEnoughArguments] if args is nil. To maintain backward 
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compatibility with existing messages, the string array is one origin (that is, the field < 1 > 
accesses args[0]; 

ComposeOneToFormatHandle: procedure [ 

source: xstring.Reader, destination: XFormat.Handler arg: xstring.Reader]; 

ComposeOne: procedure [ 

source: xstring.Reader, destination: xstring.Writer, arg: xstring.Reader]; 

ComposeOneToFormatHandie and ComposeOne compose a message by replacing the 
single field in source with arg. ComposeOneToFormatHandle uses an xFormat. Handle as 
the destination of the message, while ComposeOne uses an xstring.Writer. The single field 
is specified by empty angle brackets, < > . These operations may raise Error[invalidString] 
if source is empty and Error[notEnOughArguments] if arg is nil. 

Decompose: procedure [source: xstring.Reader] returns [args: StringArray]; 

Decompose currently does nothing. 

57.2.4 Defining Messages 

Messages are defined by constructing an array of message entries and registering them 
with the system. 

Messages: TYPE ■ long descriptor for array of MsgEntry; 

MsgEntry: TYPE » record [ 
msgKey: MsgKey, 
msg: xstring.ReaderBody, 
transiationNote: long string*- nil, 
translatable: BOOLEAN 4- TRUE, 
type: MsgType <- userMsg, 
id: MsgID]; 

MsgKey: type » cardinal; 

Msglype: type » {userMsg, template, argUst, menuitem, pSheetitem, commandltem, 
errorMsg, infoMsg, promptitem, windowMenuCommand, others}; 

MsgiD: type a cardinal; 

Messages describes a group of message entries and is a parameter to RegisterMessages. A 
MsgEntry contains information about each message. The msgKey field is the Handle- 
relative key of the message. The msg field contains the text of the message itself, while all 
other fields are to help in the translation process. The tranlationNote field provides notes 
to the translator. The translatable boolean indicates whether the message should be 
translated. The MsgType enumerated provides a hint of how the message will be used. 
The MsgID is a unique identifier for the message. For a given group of messages, each 
message should have a unique value for its MsgiD. The MsgID must remain unique for all 
time, across all releases. This ID allows the translators to determine when a new message 
has been added or an old message deleted. 
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AllocateMessages: procedure [ .Mi 
appiicationName: long string, maxMsglndex: cardinal, 
clientData: ClientData, proc: OestroyMsgsProc] 
returns [h: Handle]; 

CiientOata: TYPE ■ LONG pointer; 

DestroyMsgsProc: type a procedure [dientOata: ClientData]; 

AllocateMessages allows a client to define a domain of messages for subsequent registry 
and access. All access to messages will be relative to the returned handle. The 
appiicationName parameter names the message domain to the message implementation. 
maxMsgindex deHnes the maximum number of messages that are registered for this 
domain. The CiientOata and DestroyMsgsProc parameters are provided to notify the client 
when the DestroyMessages operation is invoked. 

RegisterMessages: procedure [ 

h: Handle, messages: Messages, stringBodtesAreReal: boolean]; 

RegisterMessages allows a client to initialize a domain of messages. It uses the 
stringBodiesAreReal boolean to decide whether to copy the byte sequences of the 
messages. If StringBodiesAreReal is false, it copies the reader body and bytes of the 
messages field in each entry of messages. If it is true, RegisterMessages copies the reader 
body of the entry and relies on the bytes to not be deallocated until after a call to 
DestroyMessages. jilli 

57.2.6 Obtaining Messages from a File 

MessagesFromFile: procedure [ 

fiieName: long string, clientData: ClientData, proc: OestroyMsgsProc] 
returns [msgOoma ins: MsgDomains]; 

MessagesFromReference: procedure [ 
file: NSFiie.Reference, clientData: ClientData, proc: OestroyMsgsProc] 
RETURNS [msgOomains: MsgDomains]; 

MsgDomains: TYPE s long descriptor for array of MsgDomain; 

MsgOomain: type > record [ 
appiicationName: xstring. Reader Body, 
handle: Handle]; 

MessagesFromFile and MessagesFromReference return a sequence of message domains 
that are name, message handle pairs. MessagesFromFile gets the messages from the file 
named fiieName in the system folder, while MessagesFromReference gets the messages 
from the file whose reference is file. Storage for msgOomains must by freed by calling 
FreeMsgDomainStorage. The ClientData and DestroyMsgsProc parameters are provided 
to notify the application when the DestroyMessages operation is invoked. 
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FreeMsgOomainsStorage: PROCfOURE [msgDomains: MsgDomains]; 

57.2.7 Destroying-Message Handles 

Destroy Messages: procedure [h: Handle]; 

DestroyMessages invokes the DestroyMsgsProc associated witii the handle and then frees 
any resources that are currently associated with h. The handle should no longer be used. 

37.2.6 Error 

Error: error [type: ErrorType]; 

ErrorType: type « { 

arrayMismatch, invalidArglndex, invalidMsgKey, InvalidMsgKeyList, 
InvalidStringArray, invalidString, notEnoughArguments}; 

57.3 Usage/Examples 

37.3.1 Structuring Applications to Use Messages 

Applications that use messages have at least two parts. The first part is the code for the 
application's functions. It is produced by programming tools such as the compiler and 
binder with Mesa source programs as input. The second part consists of the messages that 
provide text to the user. The application defines its messages and provides initial 
information to the translators of the messages. 

Messages that are to be translated must be able to communicate in a precise type-safe 
way. Throughout the translation process, it should be possible to verify the message with 
its original version. 

The cleanest and safest possible interface between application developers (message 
definers) and translators is to deliver a bed that contains all the messages used by the 
application as well as a well-defined mechanism for communicating them to some client. 
The RegisterMessages procedure provides the mechanism; all else that is needed is to 
avoid other distractions (like importing or exporting of application private facilities). To 
that end, the following conventions are proposed for modules/configurations that define 
and register messages: 

1. Isolate message definition code into modules whose sole function is to define and 
register the message text for the application. 

2. Allocate the Handle and register all messages via the modules' configuration's start 
code. 

3. If multiple modules are required to define the application messages, provide a 
configuration that starts all modules in the the correct order and provides the correct 
IMPORTS and exports. 

4. XMessage definition modules and configurations must not depend upon application- 
specific facilities. The imports list of any message-defining module should be restricted 
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to procedures defined in the XMessage interface (such as RegisterMessages, 
AllocateMessages.and so forth). 



As a consequence of 2 and 4 above, applications must provide a mechanism for 
communicating the Handle between suppliers of messages (callers of ResisterMessages) 
and users of messages (callers of GetMsg, and and so forth) . A simple solution is to have 
the message-definition module export a procedure that returns the handle. 

57.3.2 Example of Message Usage 

The following message example has three segments. The first is an interface that defines 
the messages for the example. The second is the module that provides the raw material for 
the messages. This module is used to supply the message text while running the 
application while it is being developed. It is used to supply the raw data to the message 
translators. The third part is the module that uses the messages. 

- ExampieMessage.mesa 

DIRECTORY 

XMessage using [Handle]; 

ExampleMessage: definitions = begin 

Keys: type > machine dependent { 

deiete(O), confirmDelete(l), deleteDone(3)...}: 

GetHandle: procedure RETURNS[h: xMessage.Handie]; 

END. ~ of ExampleMessage: 

-- ExampleMessageimpLmesa 

DIRECTORY ... 

ExampieMessagelmpi: program 

IMPORTS... 

EXPORTS ExampleMessage ■ begin 
h: XMessage.Handie; 

GetHandle: public procedure returns [xMessage.Handie] > {RETURN[h]}; 

DeleteMessages: XMessage. Destroy MsgsProc ■ {}; 

Init: procedure = { 

msgArray : array Keys of XMessage.Msg Entry [ 
delete: [ 

msgKey: Keys.delete.ORD, 
msg:xstring.FromSTRING["Delete"L]« 
translationNote: "Delete command name"L, 
translatable: true, 
type: menultem, 
id: 01. 
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confirmDelete: [ 

msgKey: Keys.confirmOelete.ORO, 

msg: xstring.FromSTRING["Are you sure you want to delete that item"L], 
translatable: true. 
type: user Msg, 
id: 1L 
deleteOone: [ 

msgKey: Keys.deieteOone.ORO, 

msg: xstring.FromSTRINGC'The item <1 > has been deleted**L], 
translatable: true. 
type: template, 
id: 3]]; 

h <— XMessage.AllocateMessages[ 

"Exampie"U Keys.LAST.ORO.succ. nil. DeleteMessages]; 
XMessag«.RegisterMessages[h,LOOPHOLE[LONG[DESCRiPTOR[msgArray]]], false]}; 

Initd; 

END. " of ExampleMessagelmpI 
" ExamplelmpLmesa 

OiRECTORY ... 

ExamplelmpI: program 

IMPORTS XMessage, Exam pi eMessage ■ begin 

h: XMessage.Handle a ExampleMessage.GetHandled 

DeleteOne: procedure [...]»{ 

r: xstring.Reader * XMessag«.Get[h,ExampieMessage.Keys.confirmOeiete.ORD]; 

'}:' 

}. -- of ExamplelmpI 
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58.1 Overview 

The XString interface is part of a string package that supports the Xerox Character 
Standard. It provides the basic data structures for representing encoded sequences of 
characters and some operations on these data structures. 

58.1.1 Character Standard 

The Xerox Character Code Standard derines a large number of characters, encompassing 
not only familiar ASCII characters but also Japanese and Chinese Kanji characters and 
other characters to provide a comprehensive character set able to handle international 
information-processing requirements. Because of the large number of characters, the data 
structures in XString are more complicated than a long string's simple array of ASCII 
characters, but the operations provided are more comprehensive 

Characters are 16-bit quantities that are composed of two 8-bit quantities- a character set 
and character code within a character set. The Character Standard defines how characters 
may be encoded, either as runs of 8-bit character codes of the character set or as 16-bit 
characters in which the character set and character code are in consecutive bytes. See the 
XChar chapter for information and operations on characters. 

58.1.2 Data Structures 

Three main data structures are defined by XString: Context, ReaderBody and WriterBody. 
Contexts provide information for determining how characters are encoded. Reader bodies 
and readers describe a sequence of read-only characters. Writer bodies and writers 
describe a sequence of writeable characters. 

A Context contains information about how characters are encoded in the byte sequence. 
The suffixSize field describes whether the first byte is encoded as an 8-bit character or a 
16-bit character, the prefix field contains the character set of the first character if the 
encoding is 8-bit characters, and the homogeneous field is true only if there are no 
character set shifts in the sequence of characters. 

A ReaderBody describes some read-only characters that are stored as a sequence of bytes. 
The reader body contains a pointer to the allocation unit containing the bytes, bytes, the 
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offset from the pointer to the first byte, offset, the offset from the pointer of the byte after Jill 
the last byte in the byte sequence, limit, and the context information describing how the 
first character is encoded, context. Most clients should not have to access fields of a reader 
body. Many operations take a Reader, a pointer to a reader body, as a parameter to reduce 
the number of words of parameters. 

A WriterBody describes some characters that may be edited. In addition to containing all 
the information in a reader body, it also contains an offset from the pointer to the first 
character not in the allocation unit, maxLimIt, the context that describes how the last 
character is encoded, endCdntext, and the zono that contains the allocution unit, zone. 
Writer bodies are typically passed by reference. 

The designers of XString believed there is a fundamental difference between a string that 
will only be read and one that will be constructed They folt that the major usage of strings 
was to describe and examine existing strings, not construct new ones. This difference is 
reflected in the two types, readers and writers. 

58.1.3 Operations 

There are a wide range of operations on both readers and writers. Some operations that 
return simple information about readers, such as ByteLength and Empty. Others access 
characters in a reader, such as First, NthCharacter, and Lop. The operation 
ReaderFromWriter can be used to convert a writer to a reader. 

Other operations create reader bodies from other data structures, such as FromSTRING. 
Similarity, there are operations that create writer bodies from other structures, such as 
WriterBody FromSTRING. 

Routines allocate and deallocate byte sequences of both readers and writers. 
CopyToNewReaderBody makes a copy of the characters of a reader NewWriterBody 
creates an empty writer body that can hold a given number of bytes. 
CopyToNewWriterBody is similar to NewWriterBody but initializes the writer with a 
given reader. 

Other operations compare the characters in readers: Equal checks for equality and 
Compare does a multilingual lexical comparison. There are operations for scanning 
readers for specific characters. The operation ReaderToNumber converts a reader to a 
numeric value. There are Courier description routines for both readers and reader bodies. 
There is also support for backward-accessing characters in a reader. 

Routines are provided for appending to writers and editing writers. AppendReader 
appends the characters of a reader to a writer. ReplacePiece provides a general editing 
operation for writers. Only the basic appending primitives are provided in XString. The 
XFormat interface can be used to append converted values, such as numbers, to writers. 

58.2 Interface Items 



58.2.1 Contexts 



Context: TYPE ■ machine dependent record [ 
suffixSize(0:0..6): [1..2], 
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homogeneous(0:7..7): boolean, 
prefix(0:8..15): Byte]; 

A Context contains information about how characters are encoded in the byte sequence. 
The suffixSize field describes whether the first byte is encoded as an 8-bit character or a 
16-bit character, the prefix field contains the character set of the first character if the 
encoding is 8-bit characters, and the homogeneous field is true only if there arc no 
character set shifts in the sequence of characters. 

The Character Set Standard describes how characters may be encoded as a sequence of 
bytes. They call the 8-bit character encoding stringletS and call the 16 bit character 
encoding stringletl6. In 8-bit character encoding, consecutive bytes contain character 
codes of characters in the same character set. [n 16-bit character encoding, the character 
set and character code are contained in consecutive bytes. The suffixSize field describes 
how the characters are encoded; it is 1 for 8-bit character encoding and 2 for 16-bit 
character encoding. 

The prefix field contains the character set of the first character if it is an S-bit encoded 
character. Subsequent characters in the string use this same prefix unless a character set 
or encoding transition is encountered. It is not used for 16-bit encoded characters. 

The homogeneous field is an accelerator. If it is true, some operations may be faster, ft is 
important to set it TRUE only if the byte sequence contains no character set shifts. It is 
always safe to set it to false. 

emptyContext: Context « [suffixSize: 1, homogeneous: true, prefix: 0]; 

vanillaContext: Context ■ [suffixSize: 1, homogeneous: false, prefix: 0]; 

unknownContext: Context * [suffixSize: 1, homogeneous: false, prefix: 377B]; 

emptyContext, vanillaContext, and unknownContext are three Context constants. An 
empty writer should have emptyContext as its context and endContext. vanillaContext is 

the default context. unknownContext signifies that the context is unknown. It is 
generally used only for ah end context, a context that describes the last character of a 
sequence. 

58.2.2 Readers and ReaderBodies 

Reader: TYPE ■ long pointer to ReaderBody; 

ReaderBody : type « private machine dependent record [ 
context(O): Context, 

tlmit(l): CARDINAL, 
Offset(2): CARDINAL, 

bytes(3): ReadOnlyBytes]; 

ReadOnlyBytes: TYPE ■ long pointer to readonly ByteSequence; 

ByteSequence: TYPE a record! 

packed sequence computed cardinal of Byte]; 
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Byte: type ■ Environment.Byte; 

A ReaderBody describes some read-only characters that arc stored as a sequence of bytes. 
The reader body contains a pointer to the allocation unit containing the bytes, bytes, the 
offset from the pointer to the first byte, offset, the offset from the pointer of the byte after 
the last byte in the byte sequence, limit, and the context information describing how the 
first character is encoded, context. Most clients should not have to access fields of a reader 
body. Reader bodies can be thought of as fat pointers. Many operations take a Reader, a 
pointer to a reader body, as a parameter to reduce the number of words of parameters. 

A ReaderBody is like a substring descriptor. The offset and limit fields can be changed to 
describe a subsequence of bytes. Routines such as Lop and ScanForCharacter take 
advantage of this substring-like behavior. 

nullReaderBody: ReaderBody « [ 

limit: 0, offset: 0, bytes: nil, context: vanillaContext]; 

nullReaderBody defines a null value for a reader body. To test for an empty reader body, it 
should not be compared to nullReaderBody. The operation Empty should be used instead. 

58.2.3 Writers and WriterBodies 

Writer: TYPE « long pointer to WriterBody; 

WriterBody: TYPE > private machine dependent record [ 
context(O): Context, 

llmit(l): CARDINAL, 

offset(2): cardinal, 
bytesO): Bytes, 
maxLimit(5): cardinal, 
endContext(6): Context, 
zone(7) : uncounted zone] ; 

Bytes: type ■ long pointer to ByteSequence; 

Writers describe a sequence of bytes that may be changed. Writers are bit- wise compatible 
with a reader and contain additional information for storage management and appending 
characters. The maxLimit field describes the limits of the allocation unit, the zone field is 
the zone used for allocating and freeing the bytes, and the endContext field is an 
accelerator for operations that append characters. 

By including a zone in the writer body, operations that add characters to the writer can 
allocate a larger byte sequence, copy the old bytes, and update the byte pointer in the 
writer body without invalidating the writer variable that the caller owns. 

nullWriterBody: Writer Body « [ 

limit: 0, offset: 0, bytes: nil, context: vanillaContext, maxLimIt: 0, 
endContext: vanillaContext, zone: nil]; 

nullWriterBody defines a null value for a writer body. 
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58.2.4 Simple Reader Operations 

ByteLength: procedure [r: Reader] returns [cardinal] ■ inline 
ByteLength returns the number of bytes in r. If r is nil, it returns zero 
CharacterLength: procedure [r: Reader] returns [cardinal]; 

CharacterLength returns the number of logical characters in r P'loating accent characters 
are treated as separate logical characters. If r is nil, it returns zero. If r is a valid reader, 
then ByteLength[r] a 0 iff CharacterLength[r] « 0. If r contains an invalid encoding, 
CharacterLength raises the error InvaiidEncoding. 

Dereference: procedure [r: Reader] returns [rb: ReaderBody]; 

Dereference returns nullReaderBody if r is nil and r | otherwise. 

Empty: procedure [r: Reader] returns [boolean] « inline 

Empty returns true if r is nil or ByteLength[r] > 0. 

Readerlnfo: procedure [r: Reader] returns [context: Context. startsWith377B: boolean] ; 

Readerlnfo returns the context of the reader and whether the first byte of the reader is 
377B, the character set shift code. 

38.2.3 Accessing Characters 

Because of the large number of characters in the character set standard and the way they 
are encoded, it is normally not possible to access characters of a reader by inde.xing. 
Instead, a number of operations are provided to access characters. 

Character: type ■ xchar.Character; 

First: procedure [r: Reader] returns [c: Character]; 

First returns the first logical character. It is equivalent to NthCharacter[s, 0] but is usually 
more efficient. If Empty(r], then XChar.not is returned. It may raise the InvaiidEncoding 
error. 

NthCharacter: procedure [r: Reader, n: cardinal] returns [c: Character]; 

NthCharacter returns the nth logical character. Floating accent characters are treated as 
separate logical characters. First should be used if n = 0. If CharacterLength [r] < a n 
then XChar.not is returned. It may raise the InvaiidEncoding error. 

Lop: PROCEDURE [r: Reader] returns [c: Character]; 

Lop removes the first character from the front of a reader and returns it. If r is empty, it 
returns XChar.not. If r contains one logical character, Lop sets r to be empty and returns 
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the first logical character. Otherwise, Lop modifies r to point to the second logical 
character and returns the first. It may raise the invalidEncoding error. 

Map: PROCEDURE [r: Reader, proc: MapCharProc] returns [c: Character]; 

MapCharProc: type > proc [c: Character] returns [stop: boolean]; 

Map enumerates the reader, calling proc once for each character in r. If proc returns true 
it returns that character: otherwise, it returns XChar.not. It is equivalent to: 

FOR i: CARDINAL IN [O..CharacterLength[r]) do 

IF proc[c 4- NthCharacter[r, i]] then return[c]; enoloop 
RETURN[XChar.not] ; 

Map may raise the InvalidEncoding error. 

58.2.6 Errors 

Error: error [code: ErrorCode] ;. 

ErrorCode: type » { 

invalidOperation, muttipleCharSets, tooManyBytes, invalidParameter}; 

invalidOperation An invalid opei'ation has been attempted. 

nnultipleCharSets InitBreakTable has been called with a reader that contains multiple 
character sets. 

tooManyBytes A long string has been passed to FromSTRING or 
WriterBodyFromSTRING and the string contains too many bytes. 
These operations use the string as the byte pointer so the offset is 
non-zero, reducing the number of bytes it may hold. This is also 
raised by CopyReader for a similar reason. 

invalidParameter An operation has been invoked with an invalid parameter. 

invalidEncoding: error [invalidReader: Reader, firstBadByteOffset: cardinal] ; 

Operations raise the error InvalidEncoding when they detect a sequence of bytes that is 
not a valid character encoding. Although two character set shifts with no intervening 
character is an invalid encoding according to the character standard, only ValidateReader 
raises InvalidEncoding if it detects that case. The other operations ignore the first 
character set shift. Invalid encodings include ending with a character set shift or partial 
character set shift and having a non-zero byte following two 377B bytes. 

58.2.7 Conversion to Readers 

ReaderFrom Writer: procedure [w: Writer] returns [Reader] ■ inline ... ; 

ReaderFromWriter provides a conversion from the type Writer to the type Reader. This 
operation takes advantage of the fact that the first part of writer bodies are bit- wise 
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compatible with reader bodies, and hence this operation simply loopholes the writer into 
the reader. 

FromBlock: procedure [ 

block: Environment.Block, context: Context <-vani I laContext] returns [ReaderBody]; 

FromBlock returns a reader body that describes the block. 

FromChar: procedure [char: long pointer to Character] returns [ReaderBody]; 

FromChar returns a reader body that describes the character The pointer to the character 
must remain valid for the lifetime of the reader body. 

FromNSString: procedure [s: NSString.String, homogeneous: boolean false] 
RETURNS [ReaderBody]; 

FromNSString returns a reader body that describes the characters in the NSString. The 
context of the reader body is [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. 

FromSTRING: procedure [s: long string, homogeneous: boolean false] 
RETURNS [ReaderBody]; 

FromSTRING returns a reader body that describes the characters in the long string. The 
context of the reader body is [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. This 
operation may raise Error[tooManyBytes] if the string contains more than cardinal.last - 
StringBody.SiZE * Environment. bytesPerWord bytes. 

58.2.8 Reader Allocation 

CopyReader: procedure [r: Reader, z: uncounted zone] returns [new: Reader]; 

CopyReader makes a copy of the reader body and characters of r, allocating from z as a 
single allocation unit, the byte sequence for the characters, and the reader body. Note that 
this operation returns a reader, while all other operations in this interface that create a 
reader or reader body return the reader body. The reason is to avoid a double allocation 
problem in which the byte sequence and reader body are allocated from two separate 
nodes. FreeReaderBytes can be used to free the new reader and the associated bytes. Note: 
This operation may raise Error[tooManyBytes] if the reader contains more than 
CARDINAL.LAST - ReaderBody.siZE * Environment.bytesPerWord bytes. Errors in allocating 
from the zone are allowed to propagate. 

CopyToNewReaderBody: procedure [r: Reader, z: uncounted zone] returns [ReaderBody]; 

CopyToNewReaderBody allocates a copy of the bytes of r using z and returns a reader 
body describing them. If r is nil, it returns nullReaderBody. Errors in allocating from the 
zone are allowed to propagate. 

FreeReaderBytes: procedure [r: Reader, z: uncounted zone]; 

FreeReaderBytes may be used to free the storage allocated by CopyReader and 
CopyToNewReaderBody. If r is non-NiL and z is non-NiL, it frees r.bytes to the zone. When 
the reader has been obtained from CopyReader, FreeReaderBytes frees the single 
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allocation unit that contains both the reader body and byte sequence. When the reader has 
been obtained from CopyToNewReaderBody, FreeReaderBytes frees the allocation unit 
that contains the byte sequence but does not free the reader body. Errors in freeing to the 
zone are allowed to propagate. 

58.2.9 Simple Writer Operations 

ClearWriter: procedure [w: Writer]; 

ClearWriter makes w empty. It is analogous to the long string statement s.length 0. 

Writer! nfo: procedure [w: Writer] 

returns [unused: cardinal, endContext: Context, zone: uncounted zone]; 

Writerlnfo returns the number of allocated but unused bytes of a writer as well as its 
endContext and its zone. 

38.2.10 Conversion to Writers 

WriterBodyFronnBlock: procedure [block: Environment.Block, InUse: cardinal 4-0] 
RETURNS [WriterBody]; 

WriterBodyFromBiock returns a writer body that describes the block The writer body's 
ofTset and maxLimit fields are set from the block's startlndex and stopindexPlusOne 
fields, respectively. The inUse parameter sets the limit field of the writer body. If the 
block's pointer is nil or inUse is larger than the number of byles in the block, 
Error[invalidParameter] is raised. 

WriterBodyFromNSString: procedure [ 

s: NSString.String, homogeneous: boolean false] returns [WriterBody]; 

WriterBodyFromNSString returns a writer body that describes the characters in the 
NSString. Its context is [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. 

WriterBodyFromSTRING: procedure [ 

s: LONG string, homogeneous: boolean <- false] returns [WriterBody]; 

WriterBodyFromSTRING returns a writer body that describes the characters in the long 
string. Its context is [suffixSize: 1, homogeneous: homogeneous, prefix: 0]. This 
operation may raise Error[tooManyBytes] if the string contains more than caroinallast - 
StringBody.siZE * Environment. bytesPerWord bytes. 

58.2. 1 1 Writer Allocation 

NewWriterBody : procedure [maxLength: cardinal, z: uncounted zone] 
RETURNS [WriterBody]; 

NewWriterBody allocates a byte sequence that has room for maxLength bytes using z and 
returns an empty writer body that contains the bytes. Errors in allocating 
ByteSequence[maxLength] from the zone are allowed to propagate. 
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CopyToNewWriterBody: procedure [ 

r: Reader, z: uncounted zone, endContext: Context unknownContext, 
extra: cardinal 4~0] returns [w: WriterBody]; 

CopyToNewWriterBody allocates a byte sequence that has room for ByteLength[r] + extra 
bytes using z, copies the bytes of r into the newly allocated byte sequence, and returns a 
writer body that contains the bytes. The end context of the writer body is endContext. 
Errors in allocating from the zone are allowed to propagate. 

ExpandWriter: procedure [w: Writer, extra: cardinal]; 

ExpandWriter assures that at least extra bytes are available in the writer's bytes. If 
w.zone is nil, then Error[lnvalidOperation] is raised. Krrors in allocating a new byte 
sequence, if required, are allowed to propagate. 

FreeWriterBytes: procedure [w: Writer]; 

FreeWriterBytes may be used to free the byte sequence of a writer as long us it was 
allocated from the writer's zone. It may be used to free the byte sequence of writers created 
by CopyToNewWriterBody and New WriterBody. If w is non-NiL and w.zone is non-NiL, it 
frees w.bytes to the zone. Note that it does not free the writer body. Errors in freeing to the 
writer's zone are allowed to propagate. 

58.2.12 Comparison of Readers 

Equal: procedure [r1, r2: Reader] returns [boolean]; 

Equal returns true if and only if the number of logical characters is equal and the strings 
match when compared character by character (thta is, effectively CharacterLengthfrl] a 
CharacterLength[r2] and NthCharacter[r1, i] « NthCharacter[r2, 1] for i in the range [0.. 
CharacterLength[r1]). It may raise the InvalidEncoding error. 

Equivalent: procedure [r1, r2: Reader] returns [boolean]; 

Equivalent returns true if and only if the number of logical characters is equal and the 
strings match when compared character by character, ignoring case. It is equivalent to: 

IF CharacterLength[r1] # CharacterLength[r2] then return(false|: 
FOR i : CARDINAL IN [O..CharacterLength(r1 ]) do 

IF Decase[NthCharacter[r1, i]] # Decase[NthCharacter[r2, i]] then return(false]; 

ENDLOOP: 
RETURN(TRUE ]. 

Equivalent may raise the InvalidEncoding error. 

SortOrder: type ■ machine dependent { 

standard(O), spanish(l), swedish(2), danish(3), firstFree(4), null(377B)}; 

SortOrder is a parameter to Compare and CompareStringsAndStems that specifies the 
sort order, danish, Spanish, and Swedish differ from standard only in some characters in 
character set zero. 
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Compare: procedure [ 

r1, r2: Reader, ignoreCase: boolean 4-true, sortOrder: SortOrder *- standard] 
RETURNS [Relation]; 

CompareStringsAndStems: procedure [ 

r1, r2: Reader, ignoreCase: boolean 4-true, sortOrder: SortOrder standard] 
returns [relation: Relation, equaiStems: boolean]; 

Relation: TYPE > {less, equal, greater}; 

Compare and CompareStringsAndStems compare two readers. They return a relation 
indicating the sorted relationship of their arguments with the case of characters 
optionally ignored during the comparison. In CompareStringsAndStems, equaiStems is 
TRUE if hoth readers are equal to the length of the shorter. They may raise the 
InvaiidEncoding error. 

38.2;13 Numeric Conversion of Readers 

ReaderToNumber: procedure [ 

r: Reader, radix: cardinal 10, signed: boolean false] returns [long integer); 

ReaderToNumber converts the characters in the reader to a number. If radix is other than 
8, 10, or 16, XString.Error[invalidOperation] is raised. The syntax for a number is: 

{'-\: + }{baseN umber} {'h\'B\'d\'D\'h\'H}{scaleFactor\ ^ 

where {} indicates an optional part and "|" indicates a choice, and baseNumber and 
scaleFactor are sequences of digits. The value returned is ± baaeN umber * radix ** 
scaleFactor. The radix depends on the contexts of r and radix If r contains a 'B or 'b, radix 
is 8; if it contains a *D or 'd, radix is 10, if it contains a 'h or 'H, radix is 1 6; otherwise, it is 
radix. The number scaleFactor is always expressed in radix 10. If r does not have valid 
form, or r does not contain any characters, or radix is 8 and non-octal digits are used, or 
signed is false and the reader contains a minus sign, the signal InvalidNumber is raised. If 
it is resumed, the operation returns zero. If signed is false and the number would overflow 
232-1 or signed is true and the number is not in the range [-231 231), the signal Overflow 
is raised. If it is resumed, the operation returns zero. ReaderToNumber may raise the 
InvaiidEncoding error. 

InvalidNumber: signal; 

The signal InvalidNumber is raised by the string to number operations when the string is 
the wrong syntax for a number. Resuming this signal results in the operation returning 
zero. 

Overflow: signal; 

The signal Overflow is raised by the string to number operations when the string 
describes a number that is too large. Resuming this signal results in the operation 
returning zero. ^iiiillll 
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58.2.14 Character Scanning 

ScanForCharacter: procedure [r: Reader, char: Character, option: BreakCharOption] 
RETURNS [breakChar: Character, front: ReaderBody] 

BreakCharOption: TYPE ■ {ignore, appendToFrontJeaveOnRest}; 

ScanForCharacter scans the string for the first instance of char. If char is found in r, the 
characters before it are described by front and the characters after it are described by r. 
char will be on the end of front, discarded, or left on the front of rf if option is 
appendToFront, ignore, or leaveOnRest, respectively, char will be returned as breakChar. 
If it does not encounter char in r, then front is equal to r I , as it was when the procedure 
was invoked, and rf is updated to be 0 characters long, xchar.not is returned as 
breakChar. ScanForCharacter may raise the InvalidEncoding error. 

Scan: procedure [r: Reader, break: BreakTable, option: BreakCharOption] 
RETURNS [breakChar: Character, front: ReaderBody]; 

BreakTable: type > long pointer to BreakTabieObject; 

BreakTableObject: type ■ record 
otherSets: StopOrNot stop, 
set:Environment.Byte 4-0, 

codes: packed array [0..256) of StopOrNot ALL[not]] ; 
StopOrNot: type ■ {stop, not} «- not; 

Scan is like ScanForCharacter, except that it can scan for any number of character codes in 
a particular character set. The BreakTable defines which character codes of a character set 
are scanned for. Scanning is searching for the first character, c, such that 

(xchar.Set(c] a break.set AND break.codes[xchar.Code[c]] > stop) or 
(xchar.Set[c] # break.set and break.otherSets m stop). 

The disposition of the character that terminates scanning depends on option, as in 
ScanForCharacter. If the character terminated scanning because it was in a different 
character set, xchar.not is returned as breakChar. Scan may raise the InvalidEncoding 
error. 

InitBreakTable: procedure [ 

r: Reader, stopOrNot: StopOrNot, otherSets: StopOrNot] 
returns [break: BreakTableObject]; 

InitBreakTable initializes a BreakTableObject to stop (or not stop) on the characters of r 
depending on StopOrNot. If r has multiple character sets, Error[multipleCharSets] is 
raised. InitBreakTable may raise the InvalidEncoding error. 

58.2.15 Other Reader Operations 

ComputeEndContext: procedure [r: Reader] returns [c: Context]; 
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ComputeEndContext returns the context of the last character in r. If CharacterLength[r] ^Bl 
■ 0, then emptyContext is returned. ComputeEndContext may raise the invaiidEncoding 
error. 

Descri beReader : Courier. Descri ption ; 

DescribeReader is a Courier description routine. It is provided for clients that need to 
serialize and deserialize readers. 

Descri beReaderBody : Courier.Oescri ption ; 

OescribeReaderBody is a Courier description routine. It is provided for clients that need to 
serialize and deserialize readers bodies. 

Run: PROCEDURE [r: Reader] returns [run: ReaderBody]; 

Run is like Lop, except that it deals in homogeneous runs of characters instead of single 
characters. It returns a reader body describing the first homogeneous run of r and updates 
r to remove the run. If Empty[r], it returns nuilReaderBody. It may raise the 
InvaiidEncoding error. 

VaiidateReader: procedure [r: Reader]; 

ValidateReader checks the bytes of r to ensure that it is a valid encoding. If it is not a valid 
encoding, the error InvaiidEncoding is raised. Possible invalid encodings include ending in jmn^ 
a character set shift with no character or following two successive 377B bytes by a non- 
zero byte. A null run (two character set shifts with no intervening character) is an invalid 
encoding that is checked by ValidateReader. If the offset is greater than the limit or if the 
byte pointer is nil and the offset and limit are not equal, then Error(invalidParameter] is 
raised. 

58.2.16 Appending to Writers 

The operations in this section append to writers. When there is insufficient space in the 
writer to hold the bytes to be appended, the operations attempt to allocate from the 
writer's zone a new byte sequence of sufficient size. If there is insufficient space and the 
writer's zone is NIL, the signal InsufficientRoom is raised. If it is resumed, the operations 
appends as many characters as will fit. Errors resulting from allocating from the zone are 
allowed to propagate. An expanded set of appending operations are available by using the 
XFormat interface. 

AppendReader: procedure [ 

to: Writer, from: Reader, fromEndContext: Context <- unknownContext, 
extra: cardinal 0]; 

AppendReader appends the reader to the writer. If either the reader or writer is nil, this 
operation simply returns. The end context of the writer is updated to fromEndContext if it 
is not unknownContext and ComputeEndContext[r] otherwise. The signal 
InsufficientRoom may be raised as described above. Jflll 

AppendChar: procedure [to: Writer, c: Character, extra: cardinal <-0]; 
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AppendChar appends the character to the writer. If the writer is nil, this operation simply 
returns. The signal InsufficientRoom may be raised as described above. If it is resumed, 
nothing is appended. 

AppendStream: procedure [ 

to: Writer, from: stream.Handle, nBytes: cardinal, 
fromContext: Context unknownContext, extra: cardinal <-0] 
returns [bytesTransf erred: cardinal]; 

AppendStream appends nBytes from the stream from to the writer. If either the stream or 
writer is nil, this operation simply returns. The end context of the writer is updated to 
fromEndContext if it is not unknownContext and ComputeEndContext[r] otherwise. The 
signal InsufficientRoom may be raised as described above. If it is resumed, as much of the 
reader that will fit in the space available is appended. AppendStream returns the actual 
number of bytes transferred. 

Note: A bug in the interface currently defaults the fromContext parameter to 
vanillaContext instead of unknownContext. 

AppendSTRING: procedure [ 

to: Writer, from: long string, homogeneous: boolean false, extra: cardinal *- 0]; 

AppendSTRiNG appends the string to the writer. If either the string or writer is nil, this 
operation simply returns. The end context of the writer is updated to vanillaContext if 
homogeneous is true; otherwise, its value is computed from the parameter from. The 
signal InsufficientRoom may be raised as described above. 

InsufficientRoom: signal [needsMoreRoom: Writer, amountNeeded: cardinal]; 

The append operations raise the signal InsufficientRoom when the writer does not have 
enough room to contain the appendee and the writer's zone is nil. Resuming this signal 
results in as much as possible being appended. 

AppendExtensionlfNeeded: procedure [to: Writer, extension: Reader] 
returns [did Append: boolean]; 

AppendExtensionlfNeeded checks to see if there is a period somewhere in the writer other 
than the last character. If there is, false is returned. If not, it appends a period if the writer 
does not already end in one; then it appends extension and returns true. AppendChar and 
AppendReader are also used to append, and they may raise InsufficientRoom. 

58.2.17 Editing Writers 

Piece: procedure [r: Reader, firstChar, nChars: cardinal] 
RETURNS [piece: ReaderBody, endContext: Context]; 

Piece returns a reader body that describes the firstChar through firstChar * nChars logical 
characters of r. piece describes as many characters of r that are in that range, possibly 
none if CharacterLength[r] is less than or equal to firstChar. The context of the last 
character of piece is also returned. It may raise the InvalidEncoding error. 
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ReplacePiece: procedure [ 

w: Writer, firstChar, nChars: cardinal, r: Reader, 
endContext: Context *- unknownContext]; 

RepiacePiece is an editing operation for writers. It replaces nChars of w starting at 
firstChar with the characters of r. nChars may be zero and r may be empty. If the reader is 
not empty, endContext is needed to update the end context of the writer if the piece 
replacement is at the end or to determine if there needs to be a character set shift between 
the bytes of r and the (firstChar ■»■ nChar)th character of w. If endContext is 
unknownContext, it is computed from r. The signal InsufficientRoom may be raised as 
described above if the operation resulted in a net addition of bytes. ReplacePiece may raise 
the invalidEncoding error. 

38.2.18 Conversion from Readers 

Block: PROCEDURE [r: Reader] returns [block: Environment. Block, context: Context] ; 

Block returns both a block that describes the bytes in r as well as the conte.Kt of r. Clients 
that need to examine the bytes directly may use this operation. Note: The bytes of the 
block should not be written. 

NSStringFromReader: procedure [r: Reader, z: uncounted zone] 
RETURNS [ns: NSString.String] ; 

NSStringFrorfiReader creates an NSString.String from a reader. It always copies the bytes of 
the reader into a new allocation unit allocated from the zone. The resulting string should 
be deallocated by using operations from the NSString interface. Errors from allocating 
from the zone are allowed to propagate. 

58.2.19 Reverse Character Operations 

ReverseMap: procedure [r: Reader, proc: MapCharProc] returns [c: Character]; 

ReverseMap is similar to Map, except that it enumerates the characters in reverse order. 
It is less efficient than Map because encoding characters makes backward scanning 
difficult. It may raise the InvalidEncoding error. 

ReverseLop: procedure [ 

r: Reader, endContext: long pointer to Context, 
backScan: BackScanCiosure <- [nil, nil]] 
returns [c: Character]; 

BackScanClosure: type ■ record [proc: BackScanProc, env: long pointer]; 

BackScanProc: type ■ procedure [beforePos: cardinal, env: long pointer] 
returns [pos: cardinal, context: Context]; 

ReverseLop is similar to Lop, except that it takes characters off the end of the reader. It is 
less efficient than Lop because encoding characters makes backward scanning difficult. If 
the reader is empty, it returns xchar.not. If endContext f is not unknownContext, then it 
must be correct. It may be changed by a call to ReverseLop. If ReverseLop backs up over a 
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character set shift, it sets endContextf to unknownContext. It may raise the 
InvalidEncoding error. 

The BacicScanCiosure and BackScanProc provide a way for the client to inform ReverseLop 
of the context in effect before a character set shift. If endContext f is unknownContext, 
then backScan.proc is called with a byte offset before which it desires a context and 
backScan.env. It should return a context for some position before the passed one, as well as 
the actual position corresponding to that context. Simple clients of ReverseLop need not 
provide a BackScanCtosure. It is provided for clients that have information about location 
of character set changes within the reader. 

58.3 Usage/Examples 

58.3.1 De3igning Interfaces with Readers 

Designing interfaces to use readers is more complicated than long strings. The biggest 
complication is the two-level allocation scheme involving readers -* reader bodies — > 
bytes. In most cases, the bytes are relatively static and are relatively easy to deal with. 
The main problem is determining whether to use a reader or a reader body. It helps to keep 
in mind the following guideline: keep reader bodies to describe the bytes. Save a pointer to a 
string by putting the reader body, not the reader, in the data structure. This way, you 
don't have to worry about who owns the storage for the reader body. Consider the following 
interface fragment: 

Handle:TYPE a LONG POINTER TO Object; 

Object: type ■ record [ 
next: Handle, 

count: CARDINAL, 

name: xstring.ReaderBody]; 
AddAnother: procedure tname: xstring.Reader]; 

Instead of storing the name in the object as a reader, it is stored as a reader body. A reader 
is quickly generated when needed by the expression @h.name. 

Another guideline is for a procedure to take a reader and return a reader body. The idea is 
that passing readers as parameters reduces the number of words of parameters. Returning 
reader bodies allows the client to manage the storage for the reader body. 

A third guideline is that clients should be able to pass pointers to local reader bodies. If an 
implementation kept strings passed to it by saving readers, clients would have to allocate 
the reader body from permanent storage, not from the local frame. If implementations 
keep reader bodies instead of readers, passing @localReaderBody does not result in 
dangling pointers. For example, consider the following fictional procedure that renames a 
file: 

RenameFile: PROCEDURE [oldName:xstring.Reader] > { 
rb: xstring.ReaderBody; 
rb Someinterface.GetNewNamell; 
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file '(-Soineinterface.LookupByName(oldNarne]; 
Someinterface.Renameffile: file, newName: @rb]}; 

The procedure RenameFile takes a reader that it simply passes to another operation. 
While taking a reader body is equilvalent, it is more efficient to take a reader, 
particularily when strings are just being passed around. The operation GetNewNanne 
returns a reader body. If it returned a reader, it would have to define where the storage for 
the reader body was kept. Either it would have to be global, or it would have to be 
deallocated from a known place after RenameFile was done with it. It is simpler to return 
reader bodies than to deal with the allocation problems of reader bodies; it is hard enough 
to make sure ownership of the bytes is handled correctly. The new name of the Rename 
operation is a pointer to a local reader body. Rename should copy the reader body (and the 
bytes) if it intends to save the characters. 

Warning: Avoid designing interfaces that do not allow passing pointers to local reader 
bodies. 

58.3.2 Using Readers 

One simple thing to do with strings is to pass string literals. Because there is no compiler 
support for XString, it is harder to do. The code fragment below gives an example of how to 
pass string literals: 

GetUserCmFile: procedure returns [file: Someinterface.FileHandle] » { 
rb: xstring.ReaderBody <--xstring.FromSTRING["User.cm"L]; 
file <-Someinterface.LookupByName{name: @rb]}; 

Looking at all the characters in a string for something like switch processing is another 
common operation: 

Options: TYPE ■ record [debug, verify, start: boolean false]; 

ParseSwitchesI : procedure [r: xstring.Reader] returns [options: Options] « { 
rb: xstring.ReaderBody «-xstring.Dereference[r]; 
c: xstring-Character; 
sense: boolean <- true ; 

WHILE (C XStrmg.Lop[@rb]) # XChar.nOt DO 

select c from 

'd.ORD ■ > {options.debug 4-sense; sense <- true}; 
'v.ORD a > {options. verify 4- sense; sense <- true}; 
'S.ORD ■ > {options.start sense; sense true}; 
'-.ORD ■ > senses false; 
ENDCASE ■ > sense 4- true; 
endloop; 
return}; 

ParseSwitchesI uses Lop to look at each character of r and set the appropriate option. 
Because Lop changes the reader body to remove the first character, ParseSwitchesI uses 
Dereference to copy the reader body to a local variable. 
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The operations Lop, Run, ScanForCharacter, and Scan update the reader body of their 
reader parameter. If the reader body must not be altered, it should be copied as in the 
above example. 

Parses witches2: procedure [r: xstring.Reader] returns [options: Options] ■ { 
sense: boolean <- true; 
proc: xstring.MapCharProc ■ { 

SELECT C FROM 

'd.ORD » > {optlons.debug sense; sense <~ true}; 
'v.ORD m > {options.verif y sense; sense <- true}; 
's.ORO » > {options.start sense; sense true}; 
'-.ORO ■ > sense <- false; 
ENOCASE m > sense4-TRUE; 

RETURN[stOp: FALSE]}; 

[] <~xstring.Map[r: r, proc: proc]; 

RETURN}: 

ParseSwitches2 uses Map to look at each character of r and set the appropriate option. 

38.3.3 Simple Parser Example 

Below is a simple program that accepts a sequence of characters from a procedure and 
parses them into tokens. It collects characters one a a time and appends them to the writer 
buffer. If the string of characters is empty, it returns a keyword token of invalid. If the 
first character is a digit, it returns a number token, converting the string into the number. 
Otherwise it compares the string with the four keywords. If it is not a keyword, it copies 
the string from the buffer to a new reader and returns the ID token. 

— Example.mesa 

DIRECTORY 

XString using! 

AppendChar, Character, ClearWriter, Empty, Equal, First, invalidNumber, 
NewWriterBody, OverFiow, Reader, ReaderBody, ReaderFromWriter, 
ReaderToNumber, WriterBody]; 

Example: PROGRAM IMPORTS XString * { 
OPEN XString; 

TokenClass: type ■ {keyword, id, number}; 

Keyword: type ■ {begin, end, do, endloop, eof, invalid}; 

Token: type ■ record [ 

select class: TokenClass from 

keyword ■ > [keyword: Keyword], 

id ■ > [id: ReaderBody], 

number * > [number: long integer], 

enocase]; 

Input: TYPE ■ PROCEDURE RETURNS [Character]; 
eof , space: Character a . . . ; 

keywords: long descriptor for array Keyword[begin..endloop] of ReaderBody a . . . ; 
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zone: uncounted zone 4-...; 

buffer: WriterBody *- NewWriterBody(maxLength: 40. z: zone] : 

Parse: procedure [input: Input] returns [token: Token] a { 
r: Reader ReaderFromWriter[@buffer]: 
c: Character; 
OearWnter(buffer]; 
00 

SELECT (C 4- inputQ) FROM 

space ■ > exit; 

eof « > RETURN([keyword(iF Empty(rl then invalid else eof]]]; 
enocase a > AppendChar(@buffer, c]; 

ENOLOOP; 

IF Empty(r] then RETURN([keyword(invaiid]]; 
IF First(rl in ['0.oro..'9.oroJ then { 

token *- [number[ReaderToNumber(r, 10 ! 

I nvalidNumber, Overflow a > {token 4- [keyword[invalid]]; continue}]]]; 

return}; 
select true from 

Equal(r. @keywords(begin]] a > token 4-[keyword[begin]]; 

Equal[r, @keywords(end]] a > token [key word(end]]; 

Equal [r, @keywords(dol] a > token 4— [keyword[do]]; 

Equai[r. @keywords[endloop]] a > token 4— [keyword(endloop]]; 

ENOCASE a > 

token 4- [id(CopyToNewReaderBody[r: r, z: zone]]]; 
return}; 

}-.. 
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59.1 Overview 

The XTIme interface provides functions for acquiring and editing times into strings or 
strings into times. It provides the same function as the XDE Time interface but deals with 
xstring.Readers instead of LONa strings. 

59.2 Interface Items 

59.2.1 Acquiring Time 

Current: procedure returns [time: System.GreenwichMeanTime]; 

Current returns the current time. 

ParseReader: procedure [ 

r: xstring.Reader, treatNumbersAs: TreatNumbersAs «- day Month Year] 
RETURNS [time:System.GreenwichMeanTime, notes: Notes, length: cardinal]; 

ParseWithTemplate: procedure [r, template: xstHng.Reader] 

RETURNS [time: System.GreenwichMeanTlme, notes: Notes, length: cardinal]; 

TreatNumbersAs: type ■ {dayMonthYear, monthOayYear, yearMonthOay, 
yearOayMonth, day YearMonth, month YearOay}; 

The ParseReader procedure parses the reader r and returns a GMT time according to the 
Pilot standard. treatNumbersAs indicates how to interpret r. ParseWithTemplate parses r 
according to template, template serves as an interpreter for deriving time fields from r 
(see § 59.3). The date syntax is a somewhat less restrictive version of RFC733; full RFC733 
is recognized, plus forms like "month day, year", "mm/dd/yy", and variations with Roman 
numerals used for the month. The form "year month day" is also accepted if the year is a 
full four-digit quantity. Forms with "-" instead of significant space are also acceptable, as 
well as forms in which a delimiter (space or "-") can be elided without confusion. The time 
is generally assumed to be in RFC733 format, optionally including a time zone 
specification. In addition, am or pm may appear following the time (but preceding the time 
zone, if any), notes is interpreted as described below, length indicates the number of 
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characters consumed by the parser (that is, it is the index of the first character of the 
argument that was not examined by the parser). This procedure can raise the error 
Unintelligible. 

Notes: type ■ {normal, noZone, zoneGuessed, noTime, timeAndZoneGuessed}; 

Notes is used as one of the return values from the call on ParseReader. normal means the 
value returned is unambiguous; noZone means that a time-of-day without a time zone 
indication was present. (The local time zone as provided by System. LocalTimeParameters is 
assumed.) zoneGuessed is returned instead of noZone if local time parameters are not 
available; the time zone is assumed to be Pacific Time (standard or daylight time is 
determined by the date). noTime and timeAndZoneGuessed are equivalent to noZone and 
zoneGuessed respectively, where the time is assumed to be 00:00:00 (local midnight). 

Unintelligible: error [vicinity: cardinal]; 

If ParseReader cannot reasonably interpret its input as a date, Unintelligible is raised: 
vicinity gives the approximate index in the input string where the parser gave up. 

59.2.2 Editing Time 

Append: procedure [ 

w: xstring.Writer,time: System.GreenwichMeanlime <H-defaultTime, 
template: xstring.Reader dateAndlime, Itp: LIP useSystem]; 

Append appends the time in human-readable form to w. template determines which fields 
are appended. Itp provides the local time parameters (discussed below). 

Format: procedure [ 

xf h: XFormat-Handle NIL, time: System.GreenwichMeanTime defaultTime, 
template: xstring.Reader 4~ dateAndTime, Itp: LIP useSystem]; 

Format converts time to a string by calling xTime.Append using template to specify which 
template to use. xfh.proc is then called. If time is defaulted, the current time is used. 

Pack: PROCEDURE [unpacked: Unpacked, useSystemLTP: boolean <- true] 
RETURNS [time: System.GreenwichMeanTime]; 

Pack converts unpacked into the Pilot-standard System.GreenwichMeanTime. 
useSystemLTP indicates that Pack should use the system's parameters. If the local time 
parameters are not available to Pilot, System.LocalTimeParametersUnknown is raised. If 
unpacked is invalid, Invalid is raised. 

Packed: type ■ System.GreenwichMeanTime; 

Packed is retained for compatability. 

Unpack: procedure [ 

time: System.GreenwichMeanTime ^defauitTime, Itp: LTP <— useSystem] 

returns [unpacked: Unpacked]; 
Unpack converts time into its unpacked representation. If time is defaulted, the current 
time is used. Itp provides local time parameters. If the local time pdrarpeters are not 



Viewpoint Programmer's Manual 



59 



available to Pilot, System.LocalTimeParametersUn known is raised. If time is invalid, 
Invalid is raised. 

Unpacked: type ■ record[ 

year: [0..2104L month: [0..12K day: [0..31], 

hour: [0..24), minute: [0..60), second: [0..60), 

weekday: (0..6], dst: boolean, zone: System.LocalTimeParameters]; 

Unpacked values record dates by their pieces. The fields are filled by Unpack, described 
above, which operates on the time and date as kept internally by Pilot, year = 0 
corresponds to 1968. For month, January is numbered 0, l,and so forth. Days of the month 
have their natural assignments. For weekday, Monday is numbered 0. dst indicates 
Daylight Standard Time, zone indicates time zones. 

LTP: TYPE « RECOROC 
r: SELECT t: * FROM 

useSystem « > []. 

useThese ■ > [Ipt: System.LocalTimeParameters]] 
enocase]; 

LTP passes local time parameters to several procedures. Usually they are defaulted to the 
system's parameters. 

Invalid: error; 

59.2.3 Useful Constants and Variables 

dateAndTime: xstring.Reader; 
dateOnly: xstring.Reader; 
timeOniy: xstring.Reader ; 

These variables are templates that are supplied by XComSoftMessage for use in the 
Append operation. 

defaultTime: System.GreenwichMeanTime ■ System.gmtEpoch; 

defaultTime always means the current time. 

useSystem: useSystem LTP » [useSystem[]]; 
useGMT: useThese LTP ■ [useThese[[west, 0, 0, 0, 0]]]; 

These local time parameters are exported for client convenience. 
59.3 Usage/Examples 

59.3.1 Parse Reader Template Definitions 

The template for times is a reader with fields, using the standard definition of naming 
fields (that is, a number enclosed by angle brackets). The definition of the fields for times 
are: 
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ivtonLn cis u. nuiiiDcr 




L/ciy tib ci iiuxiiuisr 




X 6ur US a lour'aigit tiumu6r 




I e£Lr us u iiwo*uigib nuniDcr 




iviuntii iiciinc 




ivionbfi numc wiiin a muxiinuni oi cnrce cnaructGrs 




Hour £ts digits in rsingG [0.. 12)* 


<8> 


Hour as digits in range [0..24)* 


<9> 


Minutes, always two digits, zero-filled (e.g., 23, 04) 


<10> 


Seconds, always two digits, zero-filled (e.g., 23, 04) 


<11> 


Day of week 


<12> 


Time zone 


<13> 


AM or PM 



* If the number begins with a 0, the number is zero-filled to two digits. 
Examples 

<2>-<6>-<4> <7>:<9> l8-Nov-83 8:36 

<2> <5> <3> 18 November 1983 

<2>-<6>-<4> <7>:<9>:<10> <12>(<11>) 18-Nov-83 08:36:42 PST (Friday) 

<7>:<9> <13> 8:36AM 

< 08 >< 9 > hrs 0836 hrs 



59.3.2 Example 



— Data structure to record time in both Packed and Unpacked form. 
Data: type = record! 

startTime: xstring.ReaderBody <f-xstring.nuilReaderBody, 
endTime: xstring.ReaderBody 4-xstrmg.nuiiReaderBody, 
pStartTlme: xTime.Packed System. gmtEpoch, 
pEndTlme: XTime.Packed «-System.gmtEpoch]; 

— Retrieves, unpaclcs, stores, and displays ttie time. 
GetAndDisplayTime: PROC[packTime: XTime.Packed] « { 

time: xTime.Unpacked <-xTime.Unpack(packTime]; 
TimeOisplay [time.year, time.month, time.day]; 

}; 

ParseTimes: pROc[data: Data] ■ { 

data.pStartTime <-xTime.ParseReader[@data.startTime ! 

xTime.Uninteliigible * > Error[BadStartTime, vicinjty]].time; 
data.pEndTime 4-xTime.ParseReader[@data.endTime ! 

XTime.Uninteliigible ■ > Error[Bad EndTime, vicinity]].time; 

}; 

" Parses time into an xstring.ReaderBody 
PackedToString: pROc[time: System. GreenwichMeanTime] 
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RETURNS [rb:XString.ReaderBody <-XString.nultReaclerBody] ■ { 
template: xstnng.ReaderBody 4-xstring.FromSTRING[ 

••<2>-<6>-<4> <8>:<9>"LI; 
wb: xstring.WriterBody <~xstring.NewWriterBody(24, zone]; 
xTime. Append! @wb, time, ©template ]; 

rb *- xstring.CopyToNewReaderBody [xstring.ReaderFrom Writer[@wb], zone] ; 
xstring.FreeWriterBytes{@wb] ; 

}; 
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59.4 Index of Interface Items 



Item Page 

Append: procedure 2 

Current: procedure 1 

dateAndTime: xstring.Reader 3 

dateOniy: xstring.Reader 3 

defaultTime: constant 3 

Format: procedure 2 

invalid: error 3 

LTP: TYPE 3 

Notes: type 2 

Pack: procedure 2 

Packed: type 2 

ParseReader: procedure 1 

ParseWithTempiate: procedure 1 

timeOniy: xstring.Reader 3 

TreatNumbersAs: type 1 

Unintelligible: error 2 

Unpack: procedure 2 

Unpacked: type 3 

useGMT: constant 3 

useSystem: constant 3 



XToken 



60.1 Overview 

The XToken Interface provides general scanning and simple parsing facilities for 
collecting tokens from a character input stream. 

The basic data structure is the Object, which encapsulates the source of characters to be 
parsed. It contains a procedure that returns the next character in the input stream and 
the final character that is read from the input stream. 

The basic operations collect characters from the input stream into tokens. Clients can 
define arbitrary token classes by using filters. Clients can define their own filters or use 
one of the standard filters provided by XToken. Frequently, some portion of the input 
stream, such as blanks, are only delimiters and are usually skipped when collecting a 
token. The tjrpe SkipMode defines the options for skipping characters. Quoted tokens are a 
feature provided by XToken. By using procedures to define opening- and closing-quote 
characters, XToken allows the client to define a large number of quoting schemes. Several 
common quote procedures are supplied. 

XToken provides operations that collect standard tokens such as boolean and numeric 
values. It also provides built-in handles that understand xstring. Readers and 
Stream.Handles as sources of characters. 

Operations that return a reader body allocate their storage from the implementation's 
own heap. Clients should call FreeTokenString to release this storage. 

60.2 Interface Items 

60.2.1 Character Source Dennitions 

Handle: type » long pointer to Object: 

Object: TYPE - MACHINE DEPENDENT RECORD [ 

getChar(0):GetCharProcType, break(l): xchar.Character 4~o]; 
GetCharProcType: TYPE a procedure [h: Handle] returns [c: xchar.Character]; 
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The Object encapsulates the source of characters to be parsed. The XToken package uses jmi 
the getChar field to obtain the stream of characters. It assumes that the source has been 
exhausted when getChar returns xchar.nuil or xchar.not. XToken uses the break field to 
record the final character that it reads. It records the final character because there is no 
way to put back a character into the character source. It must read one character beyond 
the token it is parsing to ensure that it has reached the end of the input. If it simply 
returned the token, this character would be lost. Because the XToken package stores the 
last character in the Object, that character is available to the client. The client can ignore 
it, inspect it to decide what to parse next, or put it back into the character source. 

A GetCharProcType provides a stream of characters to be parsed. It should return either 
xchar.nuil or xchar.not when the stream of characters has been exhausted. The Handle Is 
passed into the GetCharProcType so that a client can hide instance data in his object. 
Although there is no instance data field in Object, the client could loophole a pointer to a 
larger record that contained its data. 

60.2.2 Filter Definitions 

FilterProcType: type » procedure [ 

c: xchar.Character, data: FilterState] returns [inClass: boolean]; 

FilterState: type » long pointer to StandardFilterState: 

StandardFllterState: type » array [0..2) of unspecified; 

A FilterProcType is the mechanism by which a client defines classes of characters. 
Procedures that use filters call them once for each candidate character. The filter should 
return TRUE if the character is in the class and false otherwise. The FilterState permits the 
filter to maintain the state of the parse. Operations that require a FilterProcType and 
FilterState initialize the StandardFilterState to allIO]. If the filter requires filter state but 
data is NIL, the signal NilData should be raised. 

Some clients' filters may need more than two words of state for their filter. In that case 
they should define a record that first contains a StandardFilterState, then define the 
additional space they need, and then loophole the filter state to a pointer to the record they 
defined. 

60.2.3 Skip Mode Definitions 

SkipMode: type = {none. whiteSpace, nonToken}; 

SkipMode controls what characters an operation skips before collecting a token. 

none No characters should be skipped, and the token should start with the 

next character. 

whiteSpace 
nonToken 



Characters such as space, carriage return, and tab should be skipped 
before collecting the token. 

Any characters that are not legal token characters should be skipped 
before collecting the token. 
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60.2.4 Quoted Token Definitions 

QuoteProcType: type » procedure [ 

c: xchar.Character] returns [closing: xchar.Character].- 

nonQuote: xchar.Character ■ . . . ; 

QuoteProcType defines the procedure used by MaybeQuoted to recognize quoted tokens. 
If c is a quote character, it should return the corresponding closing-quote character. Ifc is 
not a quote character, it should return nonQuote. 

60.2.5 Built-in Handles 

ReaderToHandie: procedure [r: xstring.Reader] 
RETURNS [h: Handle]; 

ReaderToHandie creates a Handle whose source of characters are the characters in r. The 
bytes of r are not copied, so clients are responsible for synchronizing access to the reader 
with the XToken package. 

FreeReaderHandie: procedure [h: Handle] returns [nil: Handle]; 

FreeReaderHandle destroys a Handle created by ReaderToHandie. It does not destroy the 
underlying reader. It returns nil. 

StreamToHandle: procedure [s: stream.Handle] returns [h: Handle]; 

StreamToHandle creates a Handle whose source of characters is a stream. The stream 
should signify the end of characters by raising the signal Stream. EndOfStream. 

FreeStreamHandie: procedure [h: Handle] returns [s: stream.Handle]; 

FreeStreamHandle destroys a Handle created by StreamToHandle. It returns the 
underlying stream. 

60.2.6 Boolean and Numeric Tokens 

Boolean: procedure [h: Handle, signalOnError: boolean true] returns [true: boolean]; 

Boolean parses the next characters of the source as a boolean constant. Valid boolean 
values are "TRUE" or "FALSE," but unlike the Mesa language, case does not matter 
("true" and "false" are also acceptable). In case of a syntax error, the signal SyntaxError is 
optionally raised. If signalOnError is false, or SyntaxError is resumed, then false is 
returned for a syntax error. This procedure skips leading white space. 

Number: procedure [h: Handle, radix: cardinal, signalOnError: boolean <- true] 
returns [u: LONG unspecified]; 

Number parses the next characters of the source as a number in radix radix. Numbers 
have the format specified in xstring.ReaderToNumber. In case of a syntax error, the signal 



fiO-3 



60 XToken 



SyntaxError is optionally raised. If signaiOnError is false, or SyntaxError is resumed, zero 
is returned for a syntax error. This procedure skips leading white space. 

Decimal: procedure [ 

h: Handle, sIgnalOnError: boolean true] returns [I: long integer]; 

Decimal is just like Number, but with a radix of 10. 

Octal: PROCEDURE [ 

h: Handle, signaiOnError: boolean <- true] returns [c: long cardinal]; 
Octal is just like Number, but with a radix of 8. 

60.2.7 Basic Token Routines 
Filtered: procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, skip: SkipMode ^whiteSpace, 
temporary: BOOLEAN <~ true] 
RETURNS [value: xstring. Reader Body]; 

Filtered collects the token string defined by the client's filter. If the client-instance data 
parameter data is not nil, the first two words of data are set to zero before any calls are 
made to filter, filter is called with data once on each character until it returns false. The 
string returned, which may be xstring. nuilReaderBody, must be freed by calling _ 
FreeTokenString. Leading characters are skipped according to the value of skip. If 
temporary is true, it is assumed that the string will be freed shortly, and no effort is made 
to use the minimum storage for it. If temporary is false, the minimum amount of storage 
is used, filter may raise NilOata. 

FreeTokenString: procedure Is: xstring. Reader] returns [nil: xsthng.Reader nil]; 

FreeTokenString frees bytes of the reader. It is used to free the strings allocated by 
Filtered, Item, and MaybeQuoted. It returns nil. 

Item: procedure I 

h: Handle, temporary: boolean «-true] returns [value: xstring.ReaderBody]; 

Item returns the next token delimited by white space. Leading white space is skipped and 
the characters are collected until another white-space character is encountered. The 
string returned must be freed by calling FreeTokenString. If temporary is true, it is 
assumed that the string will be freed shortly, and no effort is made to use the minimum 
storage for it. If temporary is false, only as much storage is used for the string as is 
needed. 

MaybeQuoted: procedure! 

h: Handle, data: FilterState, filter: FilterProcType NonWhiteSpace, 
isQuote: QuoteprocType <- Quote, skip: SkipMode <- whiteSpace, 
temporary: boolean <- true] 

returns lvalue: xstring.ReaderBody]; #li| 

MaybeQuoted returns the next quoted token. The first candidate character is passed to 
isQuote, which either returns nonQuote or the closing-quote character. If a closing-quote 
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character other than nonQuote is returned, characters are collected in the token until the 
closing quote is encountered. If the input is exhausted before the closing quote is 
encountered, the signal UnterminatedQuote will be raised. If it is resumed, 
MaybeQuoted returns the token collected up until that point. The closing-quote character 
may be included in the token by including two instances of the character in the input (that 
is, if MaybeQuoted encounters two closing-quote characters in a row, it inserts one 
closing-quote character in the token rather than terminating the token on the first closing 
quote). The outer quote characters are not part of the token and are discarded. If 
nonQuote is returned from the isQuote procedure, the filter is used to collect characters 
in the same way it is used in Filtered: filter is called with client-instance data parameter 
data once on each character until it returns FALSE. In either case (quoted or filtered), the 
break character returned in the Handle is the character following the token. 

Leading characters are skipped according to the value of skip. 

If temporary is true, it is assumed that the string will be freed shortly, and no effort is 
made to use the minimum storage for it. If temporary is false, only as much storage is used 
for the string as is needed. The string returned must be freed by calling FreeTokenString. 

Skip: procedure [ 

h: Handle, data: FiiterState, filter: FllterProcType, sklplnClass: boolean <- true]; 

Skip is used to skip over characters. A filter is provided to define the class of characters, 
and the boolean skipinClass indicates whether the characters to be skipped are those 
accepted by the filter or those rejected by it. If the client-instance data parameter data is 
not NIL, the first two words of data are set to zero before any calls are made to filter. If data 
is NIL and filter references data, the signal NilData should be raised. 

60.2.8 Signals and Errors 

SyntaxError: signal Ir: xstring.Reader]; 

The resumable signal SyntaxError can be raised if incorrect syntax is encountered by 
Boolean, Decimal, Number, or Octal. In each case, resuming the signal causes the 
procedure to return a default value (described in the discussion of the various procedures). 
The reader parameter is the token collected that has the wrong syntax. 

NilOata: signal; 

Procedures that take a FilterProcType argument also take an argument that is a' pointer to 
client instance data. If the client has no need for instance data, it can pass a nil as the 
instance data pointer. If a FilterProcType attempts to access the client-instance data, but 
the client passed in nil instead of a pointer to instance data, the signal NilData should be 
raised. Implementors of FilterProcTypes are strongly encouraged to check for nil and raise 
this condition if they use client-instance data. 

UnterminatedQuote:siGNAL: 

The resumable signal UnterminatedQuote is raised from MaybeQuoted if the getChar 
procedure of the Handle returns xchar.not or xchar.null before the terminating quote 
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character has been read. If the signal is resumed, MaybeQuoted returns as if it had read a 
closing-quote character. 

60.2.9 Built-in Filters 

Alphabetic: FilterProcType; 

Alphabetic defines the class of alphabetic characters (that is, the characters 'a through 'z 
and 'A through 'Z). This procedure requires no filter state. 

AiphaNumeric: FilterProcType; 

AlphaNumeric defines the class of alphanumeric characters (that is, the characters 'a 
through 'z, *A through 'Z, and '0 through '9). This procedure requires no filter state. 

Delimited: FilterProcType; 

When Delimited is passed to a procedure such as Filtered, the value of skip passed along 
with it must be nonToken. It will skip leading white space and then define the first 
character of the token to be both the opening-quote character and the closing-quote 
character, returning all characters occurring between the first and second appearance of 
that character. 

Line: FilterProcType; 

Line defines a class containing all characters except the carriage return. It can be used to 
collect a line of information. This procedure requires no filter state. 

NonWhiteSpace: FilterProcType; 

NonWhiteSpace FilterProc defines all characters that are not white space (that is, 
WhiteSpacelchar] = --NonWhiteSpaceCchar]). This procedure requires no client data (data 
may be nil.) 

Numeric: FilterProcType; 

Numeric defines the class of numeric characters (the characters *0 through *9) This 
procedure requires no filter state. 

Switches: FilterProcType; 

Switches can be used to collect switch characters. It accepts the characters , '-, and 
alphanumeric characters. This procedure requires no filter state. 

WhiteSpace: FilterProcType: 

The WhiteSpace FilterProcType defines the white space characters. This filter is used by 
Token for skipping white space. This procedure requires no filter state. 
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60.2.10 Built-in Quote Procedures 
Brackets: QuoteProcType; 

Brackets recognizes the following sets of matching opening/closing-quote pairs: (),[],{}, 
and < >. 

Quote: QuoteProcType: 

Quote recognizes single quote and double quote. 
60.3 Usage/Examples 

60.3.1 Collecting Tokens 

The following example collects name and number pairs from a stream. It uses the built-in 
stream handle provided by XToken for the source of characters. It uses the Item operation. 

ProcessltemsFromStream: procedure [stream: stream.Handie] * { 
tH: XToken.Handle <-xToken.HandteFromStream[stream]; 
name: xstring.ReaderBody *- XToken.Item(tHl; 
number: LONG integer; 
UNTiLXString.Empty[@name] oo 

number xToken.Oecimai[h: tH, signaiOnError: false]; 

Processltem[@name, number]; -do work 

[] XToken. FreeTokenString[@na me]; 

name *- xToken.item[tH]; 

ENDLOOP; 

[] «- XToken.FreeStreamHandle[tH]}; 

The following example demonstrates how the XToken interface could be used to parse 
input into tokens, optionally followed by switches. In this context, tokens and switches are 
defined to be any sequence of non-white-space characters, not including the slash 
character (/). 

GetToken: procedure returns [token, switches: xstring.ReaderBody] « 

BEGIN 

get: XToken.GetCharProcType ■ {RETURN(GetCommandLineChar(]]}; 
getToken: XToken.Object <- [getChar: get, break: xchar.not]; 
slash: xchar.Character ■ V.ord; 
MyFilter: xToken.FflterProcType ■ { 
return[select true from 

XToken. WhlteSpace[c, data], c > xchar.not ■ > false, 

c ■ slash ■ > false, 

endcase ■ > true]}; 
token XToken.Fiitered[@getToken, nil, MyFilter]; 

IF getToken.break M slash THEN switches <-xoken.Filtered[@getToken, NIL, MyFilter] 

ELSE switches xstring.nullReaderBody; 

end; 
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We can extend this example so that the token is defined to be either a sequence of non- 
white-space characters or a sequence of characters containing white space characters 
between double quotes. 

GetToken: procedure returns [token, switches: xstring.ReaderBody] a 

BEGIN 

get: XToken.GetCharProcType » {RETURNtGetCommandLineChard]}; 
getToken: xToken.Object [getChar: get, break: xchar.not]; 
slash: xchar.Character ■ V.oro; 
doubleQuote: xchar.Character * '".ORO; 
IsQuote: xToken.QuoteProcType ■ { 

return[IFc ■ doubleQuote THEN c ELSE xToken.nonQuote]}; 
MyFilter: XToken.FllterProcType ■ { 

return[selecttrue from 

xToken.WhlteSpace[c, data], c » xchar.not « > false, 

C ■ slash ■ > FALSE, 

endcase ■ > true]}; 
token 4- xToken.MaybeQuoted[@getToken, nil, MyFilter, IsQuote]; 
IF getToken.break a slash THEN switches <-xoken.Flltered[@getToken, NIL, MyFilter] 
ELSE switches 4- xstring.nullReaderBody; 
end; 
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60.4 Index of Interface Items 

Item Page 

Alphabetic: FtiterProcType 6 

AlphaNumeric: FilterProcType 6 

Boolean: procedure 3 

Brackets: QuoteProcType 7 

Decimal: PROCEDURE 4 

Delimited: FilterProcType 6 

Filtered: PROCEDURE 4 

FilterProcType: type 2 

FilterState: type 2 

FreeReaderHandle: procedure 3 

FreeStreamHandle: procedure 3 

FreeTokenString: procedure 4 

GetCharProcType: type 1 

Handle: type 1 

Item: procedure 4 

Line: FilterProcType 6 

MaybeQuoted: procedure 4 

NiiOata: signal 5 

nonQuote: xchar.Character 3 

NonWhiteSpace: FilterProcType 6 

Number: procedure 3 

Numeric: FilterProcType € 

Object: type 1 

Octal: PROCEDURE 4 

Quote: QuoteProcType 7 

QuoteProcType: type 3 

ReaderToHandle: procedure 3 

Skip: PROCEDURE 5 

SkipMode: type 2 

StandardFilterState: type 2 

StreamToHandle: procedure 3 

Switches: FilterProcType 6 

SyntaxError: signal 5 

UnterminatedQuote: signal 5 

WhIteSpace: FilterProcType $ 
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61.1 Overview 

ChartDatalnstailOefs provides the ability to install new data in a chart without regard to 
the type of the chart. Specifics such as line styles or shadings are not affected. Typical 
clients include those that have changing data depicted in chart form (e.g., one such client 
is the ViewPoint database package). 

61.2 Interface Items 

The primary type in this interface is the Handle, which points to a record of chart 
information. Clients may obtain a handle by either calling GetChartFromlnstance or 
GetChartFromSelection. Once the client has a handle, several functions can be performed 
on the chart; installing new data or validating the chart are some examples. 

Handle: TYPE » long pointer to Object- 
Object: TYPE « RECORD [ 

type: Chartlype, 

instance: InstanceDefs.lnstance, 

vaiidateChart: ValidateChartProc, 

vaildateData: ValldateDataProc, 

plot: PlotProc, 

free: FreeProcl; 

Chartlype: type ■ machine dependent 
{bar(O), lined), pie(2). Iast(15)}; 

type refers to the manner that the chart displays information, instance is a record that has 
pointers to the chart data. vaiidateChart is a call-back procedure to check if the chart can 
be edited. validateData checks the validity of new data to be installed in the chart, plot 
actually installs thedata, while free releases the handle. 

ValidateChartProc: type a PROC[h: Handle] returns 
[ChartValidity]; 
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ChartVaiidity: TYPE ■ machine dependent {ok(0),ciosecl(1), 
raadOnly(2)Jast(15)}; 

VaiidateChartProc checks the chart and returns its status. This procedure should be called 
before any attempt to operate on the chart. 

ValidateOataProc: type ■ proc[ 
h: Handle, data: Data, changes: Selections] 
returns [DataValidlty]; 

OataValidityiTYPE ■ machine dependent {ok(0), mvaiidSource(1),sizeMismatch(2), 
nonNumericValue(3), iiiegalValue(4), unknown(5), last(15)}; 

ValidateOataProc checks the validity of the new data that the client intends to install. The 
data is not actually installed in this step. 

PlOtPrOC:TYPE ■ PROC[ 

ii: Handle, data: Data, changes: Selections]; 

Seiections: TYPE ■ packed array Values op boolean; 
all: Selections ■ all[true]; 

Values: type ■ {title, data, rowLaisels, colLabels, orientation}; 

PlotProc sets the chart's data and then redraws the chart, data is a pointer to the new data 
to be installed, changes specifies exactly which data is set. 

Data: type ■ long pointer to DataRec; 
DataRec:TYPE ■ record [ 

title: XString.Reader *~ nil, 

data: DataValues, 

rowLabels: Labels <- nil, 

colLabels: Labels 4- nil, 

orientation: Orientation <- row]; 

DataValues: TYPE • long pointer to RowSeq; 
RowSeq:TYPE ■ record [ 
rows: select format: DataFormatFROM 

string •> [sequence nRows:cARDiNAL op StringRow], 

numeric ■ > [sequence nRows:cARDiNAL of NumericRow] 

endcase]; 

Labels: TYPE ■ long pointer to LabelSeq; 
LabeiSeq: TYPE ■ record [ 
sequence length :cardinal of XString.Reader]; 

Orientation: type * {column, row}; 

DataRec contains the data to be installed, title is the title of the chart, data points to a 
sequence-containing record of data values. rowLabels and colLabels point to sequence- 
containing records of row and column labels, respectively, orientation specifies whether 
columns or rows are the chart's data sets. 
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StringRow: TYPE ■ lon<3 pointer TO StringRowElements; 
StringRowElaments: TYPE ■ record [ 
SEQUENCE nCols:CARDiNAL OP XString.Reader]; 

NumericRow: TYPE ■ long pointer to NumericRowElements; 
NumarkRowElements: TYPE ■ record [ 
SEQUENa nCols:cARDiNAL OP XLReal.Number]; 

StringRow points to a sequence-containing record of readers; similarly, NumericRow 
points to a sequence-containing record of numbers. 

Hence, the data to l>e installed looks like this: 



Data 



DataRec 

title data rowLaisels coiLabels orientation 



OataValues 



i 



RowSeq 

















StringRow / NumcricRowr 



I r 



Stri ngRowEiements / 
NumericRowElements 



7 



Labels 



labe 



Seq 



XString.Read«r 

— 1 — r~ 



Labals 



Labe 



Seq 



XString.Reader 

~~l — r- 



title is an XString.Reader. 
orientation is an enumerated. 



FreeProc: type ■ PROC[h: Handle]; 



FreeProc releases the handle passed in. 



GetChartFromlnstance: proc [instance: InstanceOefsJnstance] 
RETURNS [Handle]; 

This procedure returns a handle to the chart given by instance. The result will be nil if the 
instance is not a chart. Note that a non-NiL handle doesn't guarantee that the chart is 
valid; it only guarantees that the instance is a chart. Clients should call the chart's 
validateChartProc to determine the chart's validity. 

GetChartFromSelection: proc returns [Handle]; 
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This procedure obtains a handle by converting the current selection. If the current 
selection is not a chart, nil will be returned. 

61.3 Usage 

The typical pattern of use for this module is: 

handle 4- €etChartFromSel€ction[ ]; 
IF handle # NIL THEN { 
IF handie.vaiidateChart(handle] #okTHEN { 

< < error > > 
EXIT}; 

DO 

< < get raw data > > 

< < determine pieces of data to be changed > > 

< < allocate and fill in data record > > 

IF handle.validateOata[handle, data, selections] # oic 
THEN << error >> 

handle.plot[handlerdata, selections]; 
ENDLOOP; 
handle.free[handle]; 

}; 
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Item 


Page 


ChartType: type 


1 


ChartVaiidity: type 


2 


Data: type 


2 


DataRec: type 


2 


DataVaiidity:TYPE 


2 


DataVaiues: type 


2 


FreaProc: type 


3 


GetChartFromlnstance: proc 


3 


GatChartFromSalaction: proc 


3 


Handle: type 


1 


Labels: type 


2 


LabelSeq: type 


2 


NumericRow: type 


3 


NumericRowElemants: type 


3 


Object: type 


1 


Orientation: type 


2 


PlotProc: TYPE 


2 


RowSeq: type 


2 


Selections: type 


2 


StringRow: type 


3 


StringRowElements: type 


3 


ValidateChartProc: type 


1 


VaiidateOataProc: type 


2 


Values: type 


2 
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62.1 Overview 

This interface contains data types to describe the properties of anchored frames within 
documents. It does not contain any procedures; it is intended for use with 
DocinterchangeDefs. 

62.2 Interface Items 

The chief type in this interface is the PropsRecord, which describes the properties of an 
anchored firame. 

Props: TYPE - LONG POINTER TO PropsRecord; 

ReadoniyProps: type » long pointer to readonly PropsRecord; 

PropsRecord: type » record [ 

borderStyie: BorderStyle trash. 
borderlhickness: cardinal trash, 
f rameDims: FrameDims trash. 
fixedWidth, 

fixedHeight: BOOL 4- TRASH, 
span: Span <- trash, 

verticalAlignment: VerticalAiignment <- trash, 

horizontalAlignment: HorizontalAlignment trash, 

topMarginHeight, 

bottomMarginHeight, 

leftMarginWidth^ 

rightMarginWidth: cardinal 4- trash 

]; 

BorderStyle: type ■ {invisible, solid, dashed, brol(en, dotted, 
double, sparel, spare2, spares, spare4, spares}; 

borderStyie specifies the characteristics of the lines that make up the frame border. 
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borderThkkness specifies the thickness of the frame border. This value is in units of 1/72 
inch. 

FrameDims: type ■ record [w, h: cardinal]; 

frameOims spedfies the height and width of the frame. These dimensions are also in units 
of 1/72 inch. 

f ixedWidth and f IxedHaight indicate whether the frame will expand when necessary. 

Span: TYPE ■ {partialColumn, f uilCoiumn, partiaiPage, 
filPage}; 

span specifies how much of the page the frame occupies. This is not currently in use. 
VerticaiAlignment: type ■ {top, bottom, floating}; 
HorizontalAlignment: type ■ {left, centarad, right, floating}; 

vertical and horizontalAllgnment specify the alignment of the frame relative to the page. 

topMarginHeight bottomMarginHeight ieftMarginWidth, and rightMargin Width are 
the margins of the frame, m units of 1/72 inch. 
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Item Page 

BorderStyle: type 1 

FrameOims: type 2 

HorizontalAlignment: type 2 

Props: TYPE 1 

PropsRecord: type 1 

ReadoniyProps: type 1 

Span: type 2 

VerticalAlignment: type 2 
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63.1 Overview 

The DocInterchangeDefs interface enables clients to create a new ViewPoint document or 
read an existing one. However, it does not support inserting new information or changing 
or deleting the contents of a document. 

DocInterchangeDefs provides procedures to create or read any of the basic document 
structures, such as text; textual **tiles;'' fields; headings and footings; or frames of various 
types. It does not include procedures to manipulate contents of frames, however. 

To create content within frames, the client must use interfaces specific to a particular 
frame type. GraphicslnterchangeDefs provides facilities for creating or reading graphics 
frames; TabielnterchangeDef s provides facilities for creating or reading tables. These are 
currently the only frame content interfaces available. 

63.1.1 Creating Documents 

To create a ViewPoint document, the first step is to call the procedure StartCreation. This 
sets up the data structures for the document and returns a Doc, which is a long pointer to 
an opaque type that represents the document. 

The next step is to add information to the document with various Append* procedures: 
AppendAnchoredFrame, AppendChar, AppendCoiumnBreak, AppendField, 
AppendNewParagraph, AppendPageBreak, AppendPFC (Page Format Character), 
AppendText, or AppendTile. 

With AppendAnchoredFrame, the client would typically call GraphicslnterchangeDefs or 
TablelnterchangeDefs to create the contents of the frame, and then call 
AppendAnchoredFrame to add that frame and its contents to the document. 

AppendField, AppendPFC, and AppendTile all have return values: this allows the client to 
call Append* routines recursively to add text and formatting information to fields, tiles, 
or PFC headers. 
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When the document contains all the desired information, the client should call 
FinishCreation, which returns an NSFito.Handle for the newly created file. 

63.1.2 Enumerating documents 

To enumerate the contents of an existing Viewpoint document, the client should start by 
calling Open, which opens the document and returns a Doc handle for that document. The 
next step is to call Enumerate, passing in the Doc and an EnumProcs record. The 
EnumProcs record contains a set of callback procedures, one for each of the following 
structures: anchored frame, column break, field, new paragraph, page break, page format 
character, text, tile. 

Enumerate proceeds sequentially from the beginning of the document: as It comes to 
different structures within the document, it calls the appropriate callback procedure, 
which handles it appropriately. Each of these procedures returns a boolean value stop; if 
any one of the procedures returns stop s true, the enumeration will terminate. If stop is 
never true, the enumeration will continue to the end of the document. 

When the enumeration is complete, the client should call Close to free all associated data 
structures and close any open file handles to the document. 

63.2 Interface Items 

63.2.1 Datatypes 

The basic data structure of DocInterchangeDefs is the TextContainer, which is any object 
that can contain text. A TextContainer can be a caption, document, field, heading, or 
footing. 

TextContainer: TYPE ■ RECORD [ 
var: select type: *from 

caption « > [h: Caption], 

doc ■ > [h: Doc], 

field ■ > [h: Field], 

heading ■ > [h: Heading], 

footing ■ > [h: Footing], 
endcase]; 

Caption:TYPE ■ long pointer to CaptionObject; 
CaptionObject: type; 

Doc: TYPE ■ LONG POINTER TO DocObject; 
DocObject: type; 

Field: TYPE ■ long pointer to FieldObject; 
FieldObject: type; 

Heading: type ■ long pointer to HeadingObject; 
HeadingObject: type; 
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Footing: TYPE ■ long pointer TO FootingObject; 
FootingObject: type; 

Tile: TYPE ■ long pointer TO TlleObject; 
TiieObject: type; 

Note that T«xtContainers must contain at least one newParagraph character, since the 
paragraph properties of any text are always inherited from the preceding newParagraph 
character. The Dodnterchange implementation supplies the initial newParagraph 
characters as required; the client should assume they already exist. 

63.2.2 Creating documents 

63.2.2.1 Initializing a document 

The client calls StartCreation to initiate the document creation process. 

StartCreation: PROC[ 

paginateOption: PaginateOption compress, 
wantHeadingHandies, wantFootlngHandles: bool false, 
initiaiFontProps: FofitPropso«fs.ReadoniyProps 4- nil, 
initlalParaProps: ParaPropso«f«.ReadoniyProps <- nil, 
initiaiPageProps: oocPag«PropsOtfs.ReadoniyProps ^nil] 

RETURNS [ 

doc: Doc, 

dodzn: instan€«o«f$.lzn, 
leftHeading, rightHeading: Heading, 
leftFooting, rightFooting: Footing]; 

PaginateOption: TYPE ■ {none, simple, compress}; 

paginateOption specifies the type of pagination that will occur when the client calls 
FinishCreation. It is specified here rather than in FinishCreation to enable performance 
optimizations based on the type of pagination that will eventually occur. 

compress pagination provides all the outward signs of pagination, such as page format 
properties, and leaves the structure of the document in its optimized form. 

simple pagination provides the outward signs of pagination but does not leave the 
document in its optimized form, so subsequent editing may be slower than with 
compress pagination, simple pagination is slightly faster than compress. 

none leaves the document in its raw form. This can lead to very slow editing, and 
potentially to loss of data. If the document will be more than a few pages long, client 
must specify a paginateOption other than none to avoid losing data. 

wantHeadingHandles and wantFootlngHandles specify whether the document will have 
headings and footings. 

initialFontProcs, initialParaProcs, and initiaiPageProps specify the initial properties for the 
document. If you do not specify a field of initial properties, StartCreation will use the 
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document default properties. (For information on document default properties, see 
63.2.2.5) 

In the pageProps, the client must ensure that the page margins leave at least one inch (72 
points) for text. That is, (left margin + right margin +72 <= page width), and (top 
margin + bottom margin +72 < = page height). 

StartCreation returns a Doc handle, a dodzn, and handles for headings and footings. The 
Doc handle represents the new document. The client should pass this handle to the 
Append* procedures described below to add information to the document, and then 
eventually release the handle with a call to FinishCreation. 

If the client releases the handle without ever calling any Append* routines, the file will 
contain a 1-page document containing a single nawParagraph and pagaFormat character, 
with the initial font, paragraph, and page props as specified. 

The doclzn is a storage space that holds various ''instances" (objects) within the document. 
This zone is returned as a convenience, because in the future there may be interfaces that 
require this zone as a parameter. Currently, however, the client can just elide this value. 

The heading and footing handles that are returned will be nil unless the client specified 
wantHeadingHandles or wantFootingHandies = true. If the headings or footings are 
valid, the client should call various Append* routines to add text and formatting 
information, and then later release each handle with a call to ReleaseHeading or 
ReleaseFooting. See section 63.2.2.3 for details. Jill 

63.2.2.2 Adding to a document 

The Append* routines below add various kinds of information to TextContainers. 

AppendChar, AppendFieid, AppendNewParagraph, AppendText, and AppendTiie take a 
TextContainer as a parameter and add the specified information to that container. The 
remaining procedures (AppendAnchoredFrame, AppendColumnBreak, 
AppendPageFormatCharacter, AppendPageBreak) take only a Doc, and not a general 
purpose TextContainer; other TextContainers cannot contain the various special 
characters. Note that the Append* routines are responsible for supplying the '*defaulV 
initial new paragraph characters; the algorithm is to append a new paragraph character if 
necessary. 

With all of these procedures, the client must manage the storage for the property records 
or other data structures passed in, except for handles obtained from the interface itself. 
The storage for the properties must remain valid during the call to Append*; after 
Append* returns, the client may do anything it chooses with the storage (typically, free 
it.) 

The Append* procedures often allow the client to set font, paragraph, or page properties. 
Defaulting any of these arguments will cause the newly appended text or object to inherit 
the properties of the preceding text/object and not the application-wide default properties. 

If an Append* routine returns a non-NiL handle, the client is responsible for later freeing 
that handle with a call to an appropriate Release* routine. See section 63.2.2.3 for details. 
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AppendAnchoredFrame: proc [ 
to: Doc, 

type: AnchoredFrameType, 

anchoredFrameProps: DocFram«Propso«fs.ReadoniyProps, 
content: instanc«D«fs.lnstance 4-inttan<ffO«fs.instanceNiU 
wantTopCaptionHandie, 

wantBottomCaptionHandle, 

wantLeftCaptionHandIa, 

wantRightCaptionHandle: bool false, 
anchorFontProps: FontPropsD«fs.ReadonlyProps <- nil] 

RETURNS [ 

anchoredFrame: instancaoefs.Instance, 
topCaptton, bottomCaption, 
leftCaption, rightCaption: Caption]; 

AppendAnchoredFrame appends the anchored frame type with properties 
anchoredFrameProps to the document Doc. 

AnchoredFrameType: TYPE ■ machine dependent {nil(O), bitmap, 
cuspButton, equation, graphics, IMQ, table, text, 
firstAvailable, lastAvailable(255)}; 

content is the contents of the frame. Currently, there are interfaces to support creating 
graphics frames and tables. For information on creating graphics frames, text frames, 
cuspButtons, or bitmap frames, see GraphicsinterchangeOefs. For information on 
creating table content, see TabielntarchangeOefs. 

want*CaptionHandle specifies which captions the frame should have. anchorFontProps 

specifies the font properties of the frame anchor. Changing the font properties of the 
anchor does not affect how that anchor appears on the display, but does affect the default 
properties that succeeding characters will inherit. 

AppendAnchoredFrame returns handles to the frame and its captions. The caption 
handles will be non-Nii only if the client specified true for the corresponding 
want^CaptionHandle parameter. The client must later release each valid caption handle 
with ReieaseCaption. 

The return parameter anchoredFrame currently has no use; it exists in anticipation of 
future needs. 

AppandChar: proc [ 
to: TextContainer, 
char: xchar.Character, 

fontProps: PontPropsOtfs.ReadonlyProps *- nil, 
nToAppend: cardinals- 1]; 

AppendChar appends one or more copies of the text character char to the specified 
TextContainer. nToAppend specifies the number of copies of the character that are to be 
appended; fontProps specifies the character properties. 

AppendCoiumnBreaic: proc [ 

to: Doc, fontProps: FontProiMD«fs.ReadoniyProps <- nil]; 
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AppendCoiumnBreak appends a column break character to a document. fontProps are the 
properties of the column break character, these properties do not affect the appearance of 
the character itself, but they do affect the properties that succeeding characters will 
inherit. 

AppendField:PROC[ 
to: TcxtContainer, 

fi€idProps:Fi«idPropsO«fs.ReadonlyProps, 
fontProps: FontProptD«fs.ReadonlyProps 4-nil] 
RETURNS [field: Field]; 

AppendFieid appends a field to the specified TextContainer. AppendFieid returns a field; 
the client can then add information to the field by using the Field as the TextContainer in 
other calls to Append* routines (but not AppendFieid again.) When the client is through 
with the field, it must release it via ReleaseFieid. See section 63.2.2.3. 

Note that the client cannot set the fill-in order of the fields when they are appended to the 
document. 

AppendNewParagraph: proc [ 
to: TextContainer, 

paraProps : ParaPropso«fs.ReadoniyProps nil, 
fontProps: FontProp«o«fs.ReadonlyProps 4- nil, 
nToAppend: cardinals- 1]; 

AppendNewParagraph appends one or more new paragraph characters to a 
TextContainer object. nToAppend specifies the numlser of characters to be appended. 
paraProps and fontProps specify the properties for the paragraph.If paraProps is nil, the 
new paragraph inherits the props of the previous paragraph; otherwise, paraProps 
determines the properties of the paragraph. 

Note that TextContainers always contain at least one newParagraph character. The client 
does not have to provides these initial newParagraph characters; Oocinterchange 
implementation supplies them as required. 

AppendPageBreak: proc [ 

to: Doc, fontProps: PontPropso«fs.ReadonlyProps 4-nil]; 

AppendPageBreak appends a page break character to the text of a document. The 
fontProps do not affect the appearance of the page break character itself, but they do affect 
the properties that succeeding characters will inherit. 

AppendPFC: proc [ 
to: Doc, 

pageProps:Do<PagePropsOefs.ReadonlyProps, 
wantHeadingHandles, wantFootingHandles: bool *- false, 
fontProps: FontPropsD«fs.ReadoniyProps <- nil] 

RETURNS [ 

leftHeading, rightHeading: Heading, 
leftFooting, rightFooting: Footing]; 
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AppendPFC appends a page format character to the main document text. 

pageProps specify the properties for the new page. The client must ensure that the page 
margins leave at least one inch (72 points) for text. That is, (left margin ♦ right 
margin + 72 < ■ page width), and (top margin + bottom margin + 72 < ■ paga height). 

The heading and footing handles that are returned will be NIL unless the client specified 
wantHeadingHandlesorwantFootingHandles = true. 

If the heading and footing handles are valid, the client can then use them as 
TextContainers for further calls with Append* procedures. If the headers are to be the 
same on left and right pages, only leftHeading need contain the heading; rightHeading 
should be nil. The same rule applies for leftFooting and rightFooting. 

When creating a heading or footing, the client should note that there are no automatic 
positioning parameters for information in headers and footers; the client must call the 
appropriate Append* procedures to add the desired text and position it with standard text 
formatting, such as white-space characters, paragraph alignment, leading, line height, 
and tabs. 

Additionally, there is no page number pattern; the client must place any surrounding text 
directly in the heading/footing text, inserting the # character at the position(s) where a 
page number is desired. (Note that there is a procedure, GetPageNumberOelimiter, that 
returns this character. See section 63.2.2.5 for details.) 

The client must later free every non-NiL heading or footing with a call to Releasel-leading 
or ReieaseFooting. 

AppendText: proc [ 
to: TextContainer, 
text: xstring.Reader, 
textEndContext: xstring.Context, 
fontProps: FontPropsD«fs.ReadonlyProps nil]; 

AppendText appends the text with the specified properties to the TextContainer. For 
efficiency, the client should pass the appropriate textEndContext if it is knovm (just like 
xstring.AppendReader) . 

AppendTiie: proc [ 
to: TextContainer, 
type: Atoin.ATOfWI, 
data: long pointer 4- nil, 
fontProps: FontPropsD«fs.ReadoniyProps <- nil] 
returns [tile: Tile]; 

AppendTiie is for future use. 

83.2.2.3 Releasing storage 

ReleaseCaption: proc [captionPtr: long pointer to Caption]; 
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ReieaseFieid : proc [f ieldPtr : long pointer to Field] ; ^gMI 
ReleaseHeading: proc [headingPtr: long pointer to Heading]; 
ReieaseFooting: proc [footingPtr: long pointer to Footing]; 
ReleaseTile: PROC[tilePtr: long pointer to Tile]; 

The client must call ReleaseCaption, ReieaseFieid, ReieaseFooting, ReleaseHeading or 
ReleaseTile to release resources associated with any non-NiL handle obtained from any 
Append* procedure. 

After calling Release*, the handle will be invalid. To help prevent use of an Invalid 
handle, the Release* routines take a pointer to the handle, and set the handle itself to nil. 
(This is similar to Mesa's free operation.) 

63.2^4 Finalizing document 

FinishCreation: proc [docPtr: long pointer to Ooc] 

RETURNS [ 

docFile: NSFito.Handie, 
status: FinishCreationStatus]; 

FinishCreationStatus: type ■ {oic, 

oicButNotEnoughOislcSpaceToPaginate, okBuNotEnoughVMToPaginate, ^| 
oltButUnicnownPaginateProbiem, unknownProblem}; 

When the document is complete, the client must call FinisiiCreation to finalize the 
document and release the Doc handle. FinishCreation returns an NSFila.Handie to the 
newly-created document, and a status. The file handle is valid in the current default 
NSFile session. (Note that StartCreation and FinishCreation must occur within the same 
filing session). The document that FinishCreation provides will be in paginated form if the 
client so specified in StartCreation. 

This document file is temporary, and will be purged from the NSFile system if a reboot 
occurs before it is made permanent. To make the file permanent, the client should call 
move it to the current user desktop with NSPil«.Move, followed by a call to 
starO«sktop.AddRef erence to put the icon on the display. (See section ? for an escample of 
this.) 

FinishCreationWithCheckAbortProc: proc [ 
docPtr: long pointer to Doc, 
checkAbortProc: Docum«ntD«fs.CheckAbortProc, 
cliantData: long pointer nil] 

RETURNS [ 

docFile: NSFiicHandle, 
status: FinishCreationStatus, 
aborted: boolean]; 

Docuni«ntD«fs.CheckAbortProc: proc [ciientData: long pointer] 
RETURNS [abort: BOOLEANI; 
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FinishCreationWithCheckAbortProc provides the ability to abort the document creation. 
The checkAbortProc will be called just before the document is created; if it returns true, 
the process will be aborted. At that point, the client should call AbortCreation. 

AbortCreation: proc [docPtr: long pointer to Doc] ; 

AbortCreation aborts document creation and deallocates the storage associated with that 
document. 

63.2.2.5 UtiUties 

The following procedures are utilities that may be of use to the client creating a document. 
GetFontPropsDefaults: proc [props: FontPropso«fs.Props]; 
GetPagePropsOefaults: proc [props: oocPag«Propso«fs.Props]; 
GetParaPropsOefaults: proc [props: ParaPropso«fs.Props]; 

These procedures fill in the supplied property record with reasonable default values for 
the appropriate properties. 

GatPageNumbarDelimitar: proc returns [xchar.Character]; 

When the client appends text to a heading or footing by calling AppendText, it includes a 
special page number delimeter to Indicate where the page number should appear within 
the text. GatPageNumberOeiimiter retiuns this character. 

This character will also appear in strings handed to the client during Enumeration of a 
heading/footing (below), to indicate where the page number appears in the 
heading/footing text. There may be more than one such character in a heading/footing 
string, indicating that the page number appears more than once in the heading/footing. 

SetCurrantParagraphProps: proc [ 
taxtContainer:TexKontainer, 
paraProps: ParaPropso«fs.RaadonlyProps]; 

SatCurrantParagraphProps can be called at any time, such as in the middle of a paragraph 
or (even if it makes no sense) repeatedly vdth different properties. If it is called repeatedly, 
only the most recent call will remain in effect. The client can call this procedure on any 
TaxtContainar, such as a document. 

SetCurrantParagraphProps affects the entire current paragraph, including any portion 
not yet appended at the time it is called. The properties also affect all subsequent 
paragraphs unless the client overrides the properties with new ones passed to 
AppandNewParagraph, or by another call to SatCurrantParagraphProps. 

Note, however, that setting paragraph properties on a TaxtContainar will cause an error if 
that TaxtContainar does not contain any paragraph characters. Although Doclnterchange 
does guarantee that every TaxtContainar will contain at least one new paragraph 
character, those paragraph characters are added (if necessary) during the Append* 
routines. Thus, calling SaKurrantParagraphProps before calling any Append* routines 
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will cause an error. To avoid this problem, the client can simply call AddNewParagraph 
to ensure that the TextContainer does have a paragraph character. Since the Append* 
routines only add a new paragraph if necessary, this will not cause duplication. 



63.2.3 Enumerating documents 

03.2.3.1 Open 

Open: proc[ 

docFileRef : NSFiie.Reference, 
password: xstring.Reader <~nil] 
RETURNS [doc: Doc,status: OpenStatus]; 

OpenStatus: type ■ {ok, badSeal, cantOpenlzn, incompatible, 

notLocal, outOfDiskSpaceForBackup, outOf DiskSpacaToUpgrade, 
outOfVMToUpgrade, unknownProbiem, outOfVMToOpan, accessConfiict, 
invalidPassword}; 

To enumerate a document, the first step is to call Open. Open takes a NSFito.Ref erence for a 
file and opens it for reading by returning a Doc. The client should then pass this Doc to 
Enumerate, which will parse the document. 



password is provided in anticipation of future password-locking of documents, password 
is currently ignored. 

Open also returns a status code, which can have any of the following values: 



ok 



Everything was fine 



badSeal 



The document is internally inconsistent. 



cantOpenlzn 



There isn't enough contiguous virtual memory. 



incompatible The document is more than one version old, and the upgrader 

cannot handle it. 



notLocal The document is not on the workstation, so it cannot be opened. 



OutOfDiskSpaceForBackup, outOfDiskSpaceToUpgrade 

There isn't enough disk space to perform the required operation. 



outOfVMToOpen There isn't enough contiguous virtual memory to open the 

document. 



accessConfiict 



Some other process has the document. 



invalidPasword 



The user does not have the credentials to create a new document. 



B3.2.3.2 Enumerate 



Enumerate: proc[ 



textContainer: TextContainer, 
procs: EnumProcs, 



ciientData: long pointer nil] 
RETURNS [dataSkipped: bool]; 
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Enumerate parses the contents of the specified TextContainer. 

procs is a record that contains client-defined callback procedures to enumerate the various 
kinds of structures that can be found in a TextContainer. 

EnumProcs: TYPE ■ LONGPOiNTERTOEnumProcsRecord; 

EnumProcsRecord: TYPE ■ record [ 

anchoredFrameProc: AnchoredFrameProc <~ nil, 
columnBreakProc: ColumnBreakProc <- nil, 
fieidProc: FieidProcf-NiL, 
newParagraphProc: NewParagraphProc <- nil, 
pageBreakProc: PageBreakProc 4-nil, 
pfcProc: PFCProc 4-nil, 
textProc: TextProc 4-nil, 
tileProc: TileProc 4-nil); 

Each of the procedures in an EnumProcsRecord takes as parameters the properties of the 
structure and its content when appropriate. Note that the storage for the properties passed 
to these procedures is temporary; the client must explicitly copy any properties it wishes to 
save. For a description of the various properties, see the corresponding Append* routines. 

AnchoredFrameProc: type ■ proc [ 
dientData: LONG pointer, 
type: AnchoredFrameType, 
anchorFontProps: FontPropso«fs.ReadoniyProps, 
anchoredFrame: inttanceo«fs.lnstance, 
anchoredFrameProps: DocFram«Propso«fs.ReadonlyProps, 
content: instan<eDefs.lnstance, 
topCaption: Caption, 
bottomCaption: Caption. 
leftCaption: Caption, 
rightCaption: Caption] 
returns [stop: bool <- false]; 

ColumnBreakProc: TYPE ■ PR0C[ 
ciientData: long POINTER, 
fontProps: FontPropsO«fs.ReadonlyProps] 

RETURNS [stop: BOOL 4- FALSE],* 

FieidProc: TYPE ■ proc[ 
ciientData: long pointer, 
fontProps: FontPropiD«fs.ReadoniyProps, 
fieidProps: Fi«MPropsD«fs.ReadonlyProps, 
field: Field] 

RETURNS [stop: BOOL 4- FALSE]; 

NewParagraphProc: TYPE ■ proc[ 
ciientData: long pointer, 
fontProps: FontPropsO«fs.ReadoniyProps, 
paraProps: ParaPropso«fs.ReadonlyProps] 

RETURNS [stop: BOOL FALSE]; 
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PageBreakProc: TYPE ■ PROc[ 
dientData: LONG POINTER, 
fontProps: FoiitPropsOefs.ReaclonlyProps] 

RETURNS [stop: BOOL 4- FALSE]; 

PFCProc:TYPE ■ proc[ 

clientData: LONG POINTER, 
fontProps: FontProi»D«fs.ReadoniyProps, 
pageProps: Do<Pag«PropsD«fs.ReaoionlyProps, 
leftHeading, rightHaading: Heading, 
leftFooting, rightFootIng: Footing] 

RETURNS [stop: BOOL 4- FALSE]; 

In a PFCProc, if the headers are the same on left and right pages, only leftHeading will 
contain the heading; rightHeading will be nil. (Of course, leftlHeading can be nil if it has 
no content.) The same rule applies for laftFooting and rightFooting. 

TextProc: type ■ proc [ 
ciiantData: long pointer, 
fontProps: PontPropfO«fs.ReadonlyProps, 
text: xstring.Reader, 
textEndContext: xstring.Context] 

RETURNS [stop: BOOL <- FALSE]; 

In a TextProc, textEndContext will always be accurate; it will never be 0^ 
xstring.unl(nownContext. 

TileProc: TYPE ■ proc( 

clientData: long pointer, 

fontProps: FontPropsD«fs.ReadonlyProps, 

type: Atom.ATOIVI, 

data: long pointer, 

tile: Tile] 

RETURNS [stop: BOOL 4- FALSE]; 

As it encounters an object of a particular type, Enumerate will call the appropriate 
procedure. If the client defaults a particular procedure. Enumerate will ignore any objects 
of that type. 

Each procedure has a stop return parameter; the enumeration will stop if stop ever has 
the value true. Some of the procedures also have a TextContainer handle as a parameter; 
the client can use this TexKontainer recursively in other calls to Enumerate to obtain the 
contrents of the TextContainer. 

The ciientData pointer passed in to Enumerate is passed to the callback procedures 
invoked by (that call to) Enumerate. (The ciientData may be different at different 
recursion levels, of course.) 



The handle (header, caption, etc.) supplied to the client in the call-back is readonly and is 
valid only dtiring the call-back's invocation; the client is not reponsible for releasing this 
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handle. It is possible for such a handle to be nil; a nil handle means that the corresponding 
object has no text content. 

Note that the enumeration does include the default paragraph and page format characters 
supplied with the TextContainer. Thus, when copying a document into a new document, 
the client should be careful to avoid copying the default paragraph and page format 
properties, since that would cause duplication. 

63^.3 Close 

Close: PROC[docPtr: long pointer to Doc]; 

When through with an enumeration, the client should call Close, which releases storage 
associated with the Doc handle and sets the Doc handle to NIL. 

83.2.4 Errors 

Any of the Append* procedures can raise the error NotAppended: 
NotAppended: error; 

63.3 Usage/Examples 

Here is an example of both enumeration and creation. This program adds the command 
DocEx to the Attention Window. When called, this command checks to see if the current 
selection is a document. If it is, then the program enumerates the contents of that 
document and copies the information into a new document. 

<< A DICtxtHandle is passed as dientData to procs called by 
DodnterchangeDefs.Enumerate. The record contains hartdles to the new document, and 
the old document. ignoreNewPar and ignorePFC allow the client to avoid duplicating the 
initial page format character and initial new paragraph character. > > 
DICtxtHandle: type ■ long pointer to OlCtxt; 
DICtxt: TYPE ■ record [ 

SOurceOoc, targetOoc: DocInt«rchangeD«fs.Doc, 

IgnoreNewPar, IgnorePFC: boolean]; 

TabStopsHandle: TYPE ■ long pointer to TabStops; 
TabStops: TYPE ■ record! 

list: sequence length: cardinal of ParaPropsOttfs.TabStop]; 

z: UNCOUNTED ZONE ■ HMp.systemZone; 

dlEnumProcs: Docint«rchang«D«fs.EnumProcs <>nil; 
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<<This is the command procedure. It copies the contents of the currently selected 
document to a new document > > 
MakeOoc: Mtnuoata.MenuProc ■ { 
-get reference to selected file 
IP s«l«ction.CanYouConvert[f lie] then { 

salValue: selection. Value 4- s«iaction.Convert[f He]; 
docFlleRef : NSFito.Reference ■ loophole[ 

selVaiua. value, long pointer to NSFHv.Reference] f ; 



"Open source document 
sourceOoc: Do€fnt«rchang«o«fs.Doc; 
openStatus: Do€int«rchang«D«fs.OpenStatus; 
[sourceOoc, openStatus] <- 

Doclnt«rchangeo«fs.Open[docFlieRef]; 



IP openStatus ■ ok then { 
-declare some variables 
targetDoc: Dodnt«r€iMngco«fs.Doc; 
diCtxt: OlCtxt; 
docFile: NSFiic.Handle; 
ref Doc. ref Dt: NSFii«.Reference; 
fiieDt: NSFito.Handle; 
tabStops: TabStopsHandle; 
fontProps: FontPropso«ft.PropsRecord; 
paraProps: ParaPropsD«fs.PropsRecord ; 
pageProps:oocPag«PropsD«fs.PropsRecord; 
-get props from source document, artd create new doc 
-with those props 
GetlnitialDocProps( 

docFlleRef, ©sourceOoc, @fontProps, OparaProps, 

@pageProp$, ©tabStops]; 
paraProps.tabStops 4- 

IF tabStops ■ nilthenoescriptor(NIL,0] 

ELSE OESCRiPTORC©tabStops.llst(oj, tabStops.length]; 
targetOoc oo<tntarchangeo«fs.StartCreation( 

paginateOption: simple, initialFontProps: ©fontProps, 

inltlalParaProps: ©paraProps, 

initiaiPageProps: ©pageProps].doc; 
IF tabStops # nil THEN z.FREE[©tabStops]; 
diCtxt 4~ [sourceOoc targetOoc, true, true]; 

-start enumeration 

U 4-Oodnt«rchangeO«fs.Enumerate[ 

[doc[h: sourceOoc]], dlEnumProcs, ©diCtxt]; 
-enumeration done. Oose source doc; create new doc, 
make it permament, and display it on desktop. 
Docint«r<hang«oefs.CIose[©sourceOoc] ; 
docFile 0o<int«rchang6D«fs.FinishCreation[ 

©targetOocJ.docFile; 
ref Doc NSFiie.GetRef erence[docFile]; 
ref Dt 4- starO«sktop.GetCurrentDesktopFile[]; 
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fiieDt 4- NSFii«.OpenByReference[refDt]; 
NSFii«.Move[ciocFiie, fiieDt]; « put new doc on Desktop 
NSPii«.CIose[fileDt]; 
NSFn«.Cto$e[docFile]; 

starD«sktop.AddReferenceToDeslctop[refDoc]; 

} 

ELSE UMrT«rminai.BlinkDispiay[]; 

} 

ELSEUMrT«rfflinal.BlinkDisplayn; 
}; -Ma/iceOoc 



< < The call back procedures for enumeration. They all just 

add the specified structure to the new document > > 

< <Add new paragraph to new document. If it is the first new paragraph character, then 
ignore it since new document will already have one. > > 
AppendNewParToTargetDoc: 

Docint«rchang«o«ff.NewParagraphProc ■ { 
diCtxt: DiCtxtHandle - clientData; 
iF diCtxt.ignoreNewPar then diCtxtJgnoreNewPar *~ false 
ELSEDodnt«rchang«D«fs.AppendNewParagraph[ 

[doc[h: diCtxttargetDoclL paraProps* fontProps]; 

}; 

-Append page break to new document 
AppendPageBreakToTargetDoc: 

Docint«rchang«D«fs.PageBreakProc ■ { 
diCtxt: DICtJctHandle ■ ciientData; 
Docint«rchangeO«fs.AppendPageBreak[ 
diCtxt.targetDoc, fontProps]; 

}; 

< <Add page format character to new document. If it is the first format character, then 
ignore it, since new document will already have one. > > 

AddPFCToTargetDoc: Do<int«rdiang«Dafs.PFCProc ■ { 
diCtxt: DiCtxtHandle - ciientData; 
IP diCtxt.lgnorePFC then dlCtxt.ignorePFC false 
ELSE n 4- Dodntardian««D«fs.AppendPFC( 

to: diCtxt.targetDoc, pageProps: pageProps, fontProps: fontProps]; 

}; 

-Append text to new document 
AppendTextToTargetDoc: Do<iiiterchang«D«fs.TextProc ■ { 
diCtxt: DiCtxtHandle ■ ciientData; 
Doclnt«rchangaO«fs.AppendText[ 
(doc[h: dlCtxt.targetDoc]], 
text, 

textEndContext, 
fontProps]; 
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-Copy the font, para, and page props of source document 
GettnitiaiDocProps: proc[. ..]■{.. .}; 

< < Allocate enumProcs record, and add command to attention menu. EnumProcs record 
is only interested in new paragraphs, page breaks, page format characters, and text; it 
ignores all other structures, > > 
Init: PROC ■ { 

name: xstring.ReaderBocly 4- xstring.FromSTRING(''DocEx"L]; 
diEnumProcs <- z.new[ 

Oocint«rchang«o«fs.EnumProcsRecord 4- [ 

anchoredFrameProc: nil, 

columnBreakProc: nil, 

f ieldProc: nil, 

newParagraphProc: AppendNewParToTargetDoc, 
pageBreakProc: AppendPageBreakToTargetOoc, 
pfcProc: AppendPFCToTargetDoc, 
textProc: AppendTextToTargetDoc]]; 
Att«ntlon^ddMenultem( 

MtonuOata.Createltamlz, @name, MakaDoc]]; 

}; 



InitQ; 
}. 
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63.4 Index of Interface Items 

Item Page 

AbortCreation: proc 9 

AnchoredFrameType: type 5 

AnchoredFrameProc: TYPE 11 

AppendChar: proc 5 

AppandAnchoredFrama: proc 5 

AppandColumnBreak: PROC 5 

AppandFieid: proc 6 

AppandNewParagraph: proc 6 

AppandPageBraak: proc € 

AppendPFC: proc 6 

AppendTaxt: proc 7 

AppandTila: proc 7 

Caption: type 2 

CaptionObject: type 2 

Close: PROC 13 

ColumnBraakProc: TYPE 11 

Doc: TYPE 2 

OocObjact: type 2 

0ocum«nto«fs.CheckAbortProc: proc 8 

Enumerate: proc 10 

EnumProcs: type 11 

EnumProcsRecord: type 11 

Field: type 2 

FieidObject: type 2 

FieidProc: type 11 

FinishCreation: proc 8 

FinishCreationStatus: type 8 

FinishCreationWithCheckAktortProc: proc 8 

Footing: type 3 

FootingObjact: type 3 

GetFontPropsOefauits: proc 9 

GetPagePropsOefaults: proc 9 

GetParaPropsDefauits: proc 9 

GetPageNumberOeiimiter: proc 9 

Heading: type 2 

HeadingObject: type 2 

NewParagraphProc: type 12 

NotAppended: error 13 

Open: proc 10 

OpenStatus: type 10 

PFCProc: type 12 

PageBreakProc: type 12 

PaginateOption: type 3 

ReleaseCaption: proc 7 

ReieaseField: proc 8 

ReleaseFooting: proc 8 



Item 

ReieaseHeading: proc 
RaleasaTila: proc 
SetCurrentParagrapliProps: proc 
StartCreation: proc 
TextContainar: type 
TextProc: type 
Tiie: TYPE 
TiiaObjact: type 
TilaProc: type 



Page 

8 
8 
9 
3 
2 

12 
3 
3 

12 
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64.1 Overview 

This interface contains data types used to describe the page properties of a document, such 
as page layout, column layout, and headings/footings. It does not contain any procedures; 
it is intended to be used in conjunction with DoclnterchangeDefs. 

64.2 Interface Items 

The chief type in this interface is the PropsRecord, which describes the various properties 
that can be associated with a page in a ViewPoint document. 

Props: TYPE ■ LONG POINTER TO PropsRecord; 

ReadoniyProps: TYPE ■ long pointer to readonly PropsRecord; 

PropsRecord: type ■ machine dependent record [ 
pageDims(0:0..31): PageDims trash, 
topMarginHeight(2:0..15): cardinal trash, 
bottomMarginHeight(3:0..15): cardinal 4- trash, 
l«ftMarginWidth(4:0..1 5): cardinal 4- trash, 
rightMarginWidth(5:0..1 5): cardinal 4- TRASH, 
startingPageSide(6:0..1): PageSide «~ trash, 
bindingMarginWidth(6:2..15): cardinal[0..16383] 4- trash, 
nCoiumns(7:0..6): cardinal[1..127] 4- trash, 
baiancedColumns(7:7..7): bool4-trash, 
unused7(7:8..15): packed array [8..15] OP[0..1] 4-»au{0], 
columnSpacing(8:0..1 5): cardinal 4- trash, 
startingPageNumbeK9:0..1 5): cardinal 4- trash, 
pageNumberFormat(10:0..2): NumberFormat 4- trash, 
restartPageNumbering(10:3..3): bool4-trash, 
unused10(10:4..15): packed array [4..1 5] op[0..1] 4-all[0], 
startingLineNumbeKII :0..15): cardinal 4- trash, 
iineNumberlnterval(12:0..10): cardinal(0..2047] 4- trash, 
lineNumberFormat(12:11..13): NumberFormat 4- trash, 
lineNumberLocation(12:14..15}: 
LineNumberLocation 4- trash. 
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headingStartsOnThisPage(13:0..0): bool trash, 
heaclingSameOnL6ftRightPages(13:1..1): bool <- trash, 
footingStartsOnThisPage(13:2..2): bool trash, 
footingSameOnLeftRightPages(13:3..3): bool <- trash, 
unused13(13:4..15): packed array [4.. 15] op[0..1] 4-all[0]]; 

PageOims: TYPE ■ machine dependent record [ 
w(0: 0..15): cardinal, 
h(1 : 0»1 5): cardinal]; 

PageSide: type ■ machine dependent {nil(0), l«ft(1), right(2)}; 

pageOims are the width and height of the table, in units of 1/72 inch. topMarginHeight, 
bottomMarginHeight, leftMarginWidth, and rightMarginWidth describe the page 
margins; these values are also in units of 1/72 inch. startingPageSide indicates whether 
the first page of the document should be a left-hand page or a right-hand page; nil means 
that there is no difference between the two. bindingMarginWidth is the width of the 
binding margin, if there is one. 

nColumns, balancedColumns,and coiumnSpacing determine column structure. nColumns 
is the number of columns; balancedCoiuinns specifies whether the length of the column is 
equfid to the length of the page. coiumnSpacing is the amount of space between columns, in 
units of 1/72 inch. 

startingPageNumbers, pageNumberFormat, and restartPageNumbaring describe the 
page numbering properties. startingPageNumber indicates the page number at which the 
numbering should start; restartPageNumbering specifies whether renumbering should 
restart for this page, or continue £rom where the last numbering left oK 

NumberFormat: TYPE ■ machine dependent { 

cardinal(O), iowerCaseLetter(1)« upp€rCaseLetteK2), 
lowerCaseRonian(3), upperCaseRoman(4), spare(7)}; 

pageNumberFormat specifies the format of the page number; currently only cardinal is 
implemented. 

LineNumberLocation: TYPE ■ machine dependent {ieftMargln(0), 
rightMargin(l), outarMargin(2), bothMargins(3)}; 

startingLineNumber, lineNumberinterval, lineNumberFormat, and lineNumbarLocation 
are not currently implemented. 

The remaining properties describe headings and footings. headlngStartsOnThlsPage and 
footingStartsOnThisPage indicate whether the designated heading/footing should start on 
this page or the next; HeadingSamaOnLaftRightPaga and footingSameOnLeftRightPages 
specifies whether all pages have the same heading^footing. 
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64.3 Index of Interface Items 



Item Page 

LineNumberLocation: type 2 

NumberFormat: type 2 

PageOims: type 2 

PageSide: type 2 

Props: TYPE 1 

PropsRecord: type 1 

ReadoniyProps: TYPE 1 
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66.1 Overview 

FieldPropsDefs contains data types used to describe fields in ViewPoint document. It does 
not contain any procedures; it is intended to be used in conjunction with 
OodnterchangeDefs. 

65.2 Interface Items 

The chief type in FieldPropsDefs is the PropsRecord, which describes the properties of a 
field. 

Props: TYPE ■ LONG POINTER TO PropsRecord; 

ReadoniyProps: TYPE ■ long pointer to readonly PropsRecord; 

PropsRecord: TYPE ■ record [ 

language: MuitiNatioiMi.Languag€ trash, 

length: cardinal 4- trash, 

required: boolean trash, 

sklplf : SkiplKholceType trash, 

stopOnSkIp: boolean trash, 

type: FieldChoicaType <- trash, 

filllnRuie, 

description, 

format, 

name, 

range, 

skiplfFieid: xstring.ReaderBody trash, 
f lilinRuieRuns: FontRunD«fs.FontRuns 4- trash 

1; 

language determines the format of date and amount fields. There are many formats, so 
you would have to check the format for each particular language. 

length is the length of the field, in characters. 
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required indicates whether the user is required to fill in the field. If required is true, the 
user will not be able to use next or skip to advance to the next field until this field has a 
value. 

SIciplfChoiceType: TYPE ■ machine dependent {empty, 
notEmpty, never, always}; 

sicipif defines the conditions under which the field can be skipped when the user presses 
the NEXT key. stopOnSkip specifies whether the skipping action should stop at this field or 
not. 

FieidChoiceType: TYPE ■ machine dependent {any, text, 
amount, date}; 

type specifies the type of data that can be in the field, any indicates that the field can 
contain any characters, including frames and other fields, text indicates that the field can 
contain only letters, digits, and symbols entered from the keyboard, amount indicates that 

the field can contain only numbers, spaces, and the foUovring symbols: + * $ , . 0. date 

specifies that entries in the field can contain only a date. 

f iillnRuie defines the fill-in rule for this field. 

description is posted for each field entered with the next key when "prompt for fields" is 
invoked, format controls the format in which information is presented. For a type of text, 
this property defines a required pattern that must be matched. For a type of amount or 
date, this field controls the form in which the contents of the field are presented, 
regardless of how the user enters them. For a type of any, the format property is not used. 

name is the name of the field. If no name is provided, the field will automatically be 
named Fieldn, as in Fieldl, Field2, and so on. 

range defines a specific range of acceptable entries. 

skiplfFleid contains the name of the field that will appear in the property sheet Skip if 
field. 

f illlnRuleRuns is an auxiliary data structure that the client can attach to the xstrlng. Reader 
that describes the fill-in rule for the field. A font run describes the subsequences of 
characters within a Reader that have the same font attributes. 
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66.3 Index of Interface Items 



Item 


Page 


FieidChokeTypa: type 


2 


Props: TYPE 


1 


PropsRecord: type 


1 


ReadonlyProps: type 


1 


SkiplfChokeType: type 


2 
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66.1 Overview 

This interface contains types used to describe the font properties of characters. It does not 
contain any procedures; it is intended for use with OoclnterchangeDef s. 

66.2 Interface Items 

Props: TYPf ■ LONG POINTER TO PropsAecord; 

ReadonlyProps: TYPE ■ long pointer to readonly PropsRecprd; 

PropsRecord: TYPE ■ machine dependent record [ 
fontDesc(0:0..31): FontDescription, 
offset(2:0..1 5): integer «- trash, 

foregroundBackground(3:0..1): ForegroundBackground, 
nUnderlines(3:2..3): cardinal[0..3] 4- trash, 
strik«out(3:4..4): BOOLEAN <- trash; 
piacement(3:5..7): Placement «~ trash, 
unused3(3:8..15): packed array [8..15] op [0..1] 4-au[0]]; 

The PropsRecord is the chief type in this interface.Section 66.2.2 describes the fontDesc 
field; section 7.1.2 describes the other fields in a PropsRecord. 

66.2.1 FontDescription 

FontOescription: TYPE ■ machine dependent record [ 
famlly(0:0..8): Family 4- trash, 
designVariant(0:9..10): DeslgnVarlant 4- trash, 
pltchVarlation(0:11..13): PitchVarlation trash, 
posture(0:14..1 5): Posture 4- trash, 
weight(1 :0..3): Weight trash, 
pointSize(1:4..13): cardinal[0..1023] 4- trash, 
serif ness(1 :14..1 5): Serifness 4- trash]; 

Family: type m machine dependent'{ 

century(0), frutigeKl)> titan(2), pica(3), trojan(4), vintage(S), ellte(6), letterGothic(7), 
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master(8), cubic(9), roman(IO), scientific(ll), gothic(12), bold(13), ocrB(14}« 
spokesman(15), xeroxLogo(16), century Thin(17)« scientificThin(18), helvetka(19), 
helveticaCondensecl(20), optima(21), times(22), baskerviiie(23), spartan(24), 
bocloni(25), paiatino(26), caledonia(27), memphis(28), excei$ior(29), olympian(30), 
univers(31), univ€rsCondensed(32), trend(33), boxPS(34), termmal(35), ocrA(36), 
iogo1(37). logo2(38), logo3(39K geneva2(40), times2(41), square3(42), courier(43), 
futura(44), presti9e(45). aLL6tterGothk(46), centurySchQolBook(47), f irstUnused(48), 
lastUnused(510K backstop(511)}; 

family is the font family. 

Design Variant: TYPE ■ machine dependent { 
nulKOKromand). Itailc(2)}; 

design Variant specifies whether the character is roman or italic, null is not currently a 
valid value. 

PitchVariation: TYPE ■ machine dependent { 

null(0),fixed(1), proportlonai(2), typographic(3Ktripitch(4)}; 

pitchVariant indicates the spacing of the font; null is not currently a valid value. 

Posture: type ■ machine dependent { 

nuil(0), uprightd), slanted(2), backslanted(3)}; 

posture indicates the slant (stress) of the character, if any. null is not currently a valid 
value. 

Weight: TYPE ■ machine dependent { 

nuii(0), uitraUght(1), extraLight(2), light(3), semiLight(4), medium(5), semiBoid(6), 
bold(7), extraBold(8), ultraBoid(9)}; 

weight is the thickness of the character. 

pointSize is the size of the font. Note that this value must be in the subrange [0..1023]. 

Serif ness: type ■ machine dependent { 
null(0), serif(lK sansSerif(2)}; 

serifness indicates whether or not the character has serifs, null is not currently a valid 
value. 

66^2 The other fields in ProposRecord 

offset is the offset of the character from the baseline. 

ForegroundBackground: type ■ machine dependent 
{nulKOK blackOnWhited), whiteOnBlack(2)}; 

foregroundSackground indicates the color of the character relative to the display. 
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nUnderiines indicates the number of times that the character is underlined; the value 
must be in the range [0..3]. 

strikeout indicates whether or not the character has been marked for deletion. 

Placement: <<filed>> type ■ machine oependent{ 

nulKOK sub(1), subSub(2), subSuper(3), super(4)t superSub(5), sup«rSuper(6), 
userSpecified(7)}; 

placement indicates the position of the character relative to the line. 
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66.3 Index of Interface Items 



Item Page 

DesignVariant: type 2 

Family: type 1 

FontDescription: type 1 

ForegroundBackground: type 2 

PitchVariation: type 2 

Placement: < <fileo> > type 3 

Posture: type 2 

Props: TYPE 1 

PropsRecord: type 1 

ReadoniyProps: type 1 

Serifness: type 2 

Weight: type 2 



FontRunDefs 



67.1 Overview 

FontRunOefs is a utility interface used to associate font properties with text. XString 
provides no facilities for associating font properties with text; FontRunOefs allows the 
client to create font information structures that point into XString structures to make the 
association. 

The data structiures in this interface mark font runs, which are consecutive characters 
with the same font. A FontPropsOefs.PropsRecord describes the font, while a cardinal 
value describes where the font starts in the text. 

In addition, this interface allows the client to enumerate the font runs in a given XString 
body of text. 

67.2 Interface Items 

Run: TYPE ■ MACHINE DEPENDENT RECORD [ 

props(O): FontPropsD«fs.PropsRecord, 
index(4): cardinal, 
context(5): XString.Context]; 

A Run indicates the beginning of a font run. props is the field describing the font used in 
the font run. Index is the byte offset in the byte sequence that holds the text; it is the byte 
offset from the beginning of the byte sequence to the byte after the byte nm. context is the 
XString context describing the next byte run. The context of the first byte run is contained 
in the reader body. See the next section for further explanation. 

FontRuns: TYPE ■ long pointer to FontRunsRec; 
FontRunsRec: TYPE ■ machine dependent record [ 
length(0): cardinal, 

runs(1): sequence maxLength(l): cardinal op Run]; 

FontRuns points to FontRunsRec, which is a record containing a sequence of Runs. 

RunProc: type « proc [ 
r: XString.Reader, 
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f : FontPropsDefs.Props, 

ctxt: LONG pointer] 

RETURNS [stopped: BOOLEAN 4- false]; 

EnumerateFontRuns: proc [ 
r: XString.Reader, 
runs: FontRuns, 
proc: RunProc, 
ctxt: LONG pointer] 

RETURNS [stopped: BOOLEAN 4- false]; 

EnumerateFontRuns allows you to perform some action for each font run in an 
XString.Reader. RunProc is a callback procedure that you pass to EnumerateFontRuns. If 
RunProc returns stopped ■ TRUE, the enumeration stops and EnumerateFontRuns 
returns stopped ■ TRUE, ctxt is client data that you pass to EnumerateFontRuns, which 
passes it to RunProc every time RunProc is invoked. 

67^ Meaning of Index and Context Fields in Run 

As stated earlier, index is the index into the XString of the byte following that run. 
context is the XString.Context in effect after that run. Here are two examples: 

A ReaderBody with offset = 0, limit « 12, with bytes abcdefghijkt; font runs that describe 
the furst three bytes as fontA, the next four as fontB, and the last five as fontC would be: 

fontRun 0: [props: fontA, index: 3, context: ...] 
fontRun 1 : [props: fontB, index: 7, context: ...] 
fontRun 2: [props: fontC index: 12, context: ...] 

A ReaderBody with offset = 7, limit = 19, with bytes abcdefghijkl; font runs that describe 
the first three bytes as fontA, the next four as fontB, and the last five as fontC would be: 

fontRun 0: [props: fontA, index: 10, context: ...] 
fontRun 1: [props: fontB, index: 14, context: ...] 
fontRun 2: [props: fontC, index: 19, context: ...] 
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67.4 Index of Interface Items 



Item Page 

EnumerateFontRuns: proc 2 

FontRuns: type 1 

FontRunsRec: type 1 

Run: TYPE 1 

RunProc: type 1 
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68.1 Overview 

Graphicsinterchang«Oefs provides utilities for creating and enumerating the contents of 
anchored graphics frames. It is typically used in coqjunction with DodnterchangeOef s. 

68.1.1 Creating Graphics 

To create new graphics, the client starts by calling StartGraphics, which initializes a 
graphics frame so that information can be added to it. This procedure returns a Handle, 
which is a pointer to an opaque type that contains, among other things, a graphics 
container. A graphics container is just an object that can contain graphic objects: a 
graphics container can be an anchored graphics frame, a nested graphics frame, a cusp 
button within a graphics frame, or another similar construct, such as a chart. 

Once the client has a Handle, it can pass that Handle to various Add* routines to add new 
graphics objects, such as curves, rectangles, bitmaps, and text frames, to the graphics 
frame. 

The client can also add nested frames, such as non-anchored graphics frames, cusp 
buttons, or graphics clusters, to the anchored frame. To create these structures, the client 
should call StartGraphicsFrame, StartCuspButton, or StaitCluster, respectively. Each of 
these procedures takes a graphics container as a parameter, and returns another graphics 
handle. The client can then use this as the graphics container in other calls to Add* 
routines. 

When everything has been added to a graphics container, the final step is to call a Finish* 
routine: FinlshGraphks, FinishButton, FinishGraphicsFrama, or FinishClustar. 
FinishGraphics returns a graphics handle that can be passed to DodnterchangeOefs. 

Thus, the scenario for creating a document with a floating graphics frame nested within 
an anchored graphics frame looks something like this: 

1. Call oocinterchang«o«fs.StartCraatlon to get a document handle (doc.) 

2. Call StartGraphlcs[doc] to get an anchored frame handle (h). 
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3. Call Add*(h] to add graphics to the anchored frame. 

4. Call StartGraphicsFram€ to get a handle for a nested graphics frame (gf h). 

5. Call Add *[gf hi to add graphics to the nested frame. 

6. Call FlnishGrapi€sFrame[gf h] to finish the nested frame. 

7. Call FinishGraphics[h] to complete the anchored frame and get an object of type 
inttanc«o«fs.lnstance (graphics). 

8. Call oocinttr<hifig«i}tft.AppendAnchoredFram«[graphics]. 

9. Call DocinMrdMng«o«f*.FinishCreation[@do€]. 

QS,1J2 Reading Graphics 

GraphicsInterchangeDefs also includes the facilities to read the contents of graphics 
frames. To read a graphics frame, the client should call Enumerate. Enumerate takes as 
parameters a graphics container, and a record of call back procedures, one for each of the 
following graphics objects: {bitmap frame, cusp button, cluster, curve, ellipse, form field, 
frame, image, line, point, rectange, text, triangle, other}. 

Enumerate enumerates the contents of the graphics container, calling the appropriate 
procedure for each object that it encountera. If the client does not provide a procedure for a 
particular type of object, objects of that type will be ignored. Each of the client-supplied 
enumeration procedures can stop the enumeration if it so desires. 

There are similar procedures to enumerate the contents of text frames and cusp buttons. 
EnumerateText takes as parameters a text frame and a record of procedures to handle the 
various kinds of information that can be in a text frame: fields, new paragraphs, and text. 
EnumerateButtonProgram takes a button program and a record to handle the various 
objects that can be in a button program: new paragraphs and text. 

68.2 Interface Items 

68.2.1 Creating graphics 



08.2.1.1 Star routines 

To create new graphics objects, the client must first call StartGraphics to get an anchored 
frame handle. 

StartGraphics: proc[ 

doc: DoclnterchangoD«fs.Ooc] 
RETURNS [h: Handle]; 

StartGraphics creates a new graphics frame within doc. 
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Handle: type ■ long pointer to Object; 
Object: type; 

There are also similar routines to create nested frames within a graphics container. 
StartCluster, StartGraphicsFrame, and StartButton each initialize a nested frame within a 
graphics container. All Start routines return a Handle, which the client can then pass to 
the various Add* routines to add graphics to that graphics container. 

StartCtuster: PROC[h: Handia, box: Box] returns (ch: Handle]; 

StartCiuster Initializes the set of graphics objects in h. box describes the size and location 
of the cluster relative to the anchored frame; place and dims are in micas. 

Box: TYPE ■ RECORD [place: Place, dims: Dims]; 
Place: TYPE m record [x,y: integer]; 
Dims: type ■ record [w, h: integer]; 

StartGraphicsFrame: PROC[ 
h: Handle, 
box: Box, 

frameProps: FrameProps, 
wantTopCaptionHandie. 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: boolean false] 
returns! . 

gfh: Handle, topCaption, laottomCaption, 
ieftCaption, rightCaption: Docint«rchang«D«fs.Caption]; 

StartGraphicsFrame initializes an nested graphics frame, h. box Indicates the size and 
location of the nested frame relative to the graphics container; these values are in micas. 

want*CaptionHandla indicates whether the client wants the frame to have the 
corresponding captions. If the client passes TRUE for one of these values, the corresponding 
return value will be non-NiL. The client can then use OoclnterchangeOefs routines to add 
text to the caption. Note that the caption must eventually be freed with 
oodnt«rdMiig«D«fs.RaleasaCaption. 

frameProps are the properties for the frame. 

FrameProps: TYPE ■ long pointer to FramePropsRec; 
FramePropsRec: type ■ record ( 
brush: Brush, 

expandRight, expandBottom: boolean, 

margins: array Side or cardinal, 

captionContant: array Side op oodnt«rdiangeD«fs.Caption 

]; 

Brush: type ■ record [ 
wthbrush: cardinal, 
stylebrush: StyleBrush]; 
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StyieBrush: TYPe ■ machine oepenocnt{ 

invisibMO), solid(l), dashed(2), dotted(3), double(4), 
broken(5),(15)}; 

Side: TYPE ■ {top, bottom, left, right}; 

brush describes the properties of the lines that make up the frame. The brush width is in 
micas. The standard brush widths on the property sheet are 35, 71, 106, 141, 176 and 212. 

expandRlght, expandBottom indicate whether the frame should expand automatically 
when the user puts in more information. (Only applicable to form field and text frames.) 

margins are the firame margins, in points. 

captlonContant is an array of captions associated with the frame. Note that the 
captionContent parameter is only mecuiingful during enumeration, and not during Start 
or Add routines, since the caption content is added after the frame is created. 

StartButton: PROC( 
h: Klandle, 
box: Box, 

buttonProps: ButtonProps, 

frameProps: FrameProps, 

wantProgramHandIa, 

wantTopCaptionHandie, 

wantBottomCaptionHandle, 

wantLeftCaptionHandle, 

wantRightCaptionHandIa: boolean ^ false] 

RETURNS [ 

bfh: Handle, 

buttonProgram: ButtonProgram, 

topCaption, bottomCaption, 

leftCaption, rightCaption: Docint«rchafi«eD«fs.Caption]; 

ButtonProps: TYPE ■ long pointer to ButtonPropsRec; 
ButtonPropsRec: type ■ record [name: xstring.Reader 4-nil]; 

ButtonProgram: TYPE ■ lon6 pointer to ButtonProgramObject; 
ButtonProgramObject: type; 

StartButton initializes a cusp button as a graphics container, box describes the size and 
location of the cusp button relative to the graphics container. 

buttonProps are the default properties for the button. If the client defaults this parameter, 
StartButton will generate a new unique name for the button. 

wantProgramHandle specifies whether the client wants to be able to add to the button's 
program. If the client specifies true, and is returned a valid button program handle, then 
it must later free that handle with a call to ReleaseButtonProgram (see section 68.2.1.3). 
GraphicsInterchangeDefs provides several procedures that the client can use to add data 
to the cusp program; see section, AdcUng to a cuap button, for information on these 
procedures. 
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All other properties are as described for StartGraphicsFrame. 

68.2.1.2 Adding information to a graphics container 

After calling a Start* routine to initialize a graphics container, the client will typically 
call various Add* routines to add information to the graphics container. The Add* 
routines defined below add an obg'ect to the end of the list of objects in the specified 
graphics container. 

The Add* routines are divided into two groups: geometries, and frames. The geometries 
section discusses how to add simple graphics objects: curves, ellipses, lines, points, 
rectangles, and triangles. The frames section describes how to add graphics objects in 
frames: bitmaps, form fields, images, and text frames. There is also a catch-all routine, 
AddOther, which provides the capability to add other graphics objects. 

There are also routines that add textual information to a cusp button program or to a text 
frame. These routines are at the end of the section. 

Geometries 

AddCurve: raoc [ 
h: Handle, 
box: Box, 

curveProps: CurveProps]; 

CurveProps: TYPE « LONG POINTER TO CurvePropsRec; 
CurvePropsRec: type ■ record [ 

brush: Brush, 

lineEndNW: UneEnd, 

lineEndSE: LineEnd, 

lineEndHeadNW: LineEndHead, 

lineEndHeadSE: LineEndHead, 

direction: LineOirection, 

piaceNW, placeApex, piacaSE, placePeak: Place 

1; 

LinaEnd: type ■ machine dependent 

{f lush(0), square(1 ), round(2), arrow(3)t (7)}; 

LInaEndHead: type ■ machine dependent 
{nona(O). h1(1). h2(2), h3(3). (15)}; 

LineOirectlon: TYPE ■ machine dependent 
{WE(0), NS(1), NwSe(2)« SwNe(3)}; 

AddCurve adds the curve described by curvaProps to the specified graphics container, box 
specifies the location of the curve relative to the graphics frame. If box.dims is smaller 
than the curve, only that part of the curve that fits within box.dims will be displayed. 
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brush indicates the line properties of the curve; brush is as described above for 
StartGraphicsFrame. 

lineEnd* describe the properties of the ends of the curve. lineEndNW describes the end that 
is in the West, North, or North-West; lineEndSE describes the end that is in the East, 
South, or South-East. Note that West abd East take precedence over North and South. If 
lineEnd a arrow, then HneEndHead describes the type of arrow: hi is the thinnest 
arrowhead; h3 is the thickest as shown in Figure 68.1. If lineEnd narrow, then 
linaEndHead should be none. 





hi 


► 


h2 


► 


h3 



Figure 68.1 Arrowheads 



direction is ignored; the client should always set this to WE. 



place* de^es the curve by specifying its endpoints, apex, and peak. These points are 
relative to box, and not the frame itself. Note that curves paint clockwise; clients must 
ensure that the NW endpoint appears before the SE endpoint when tracing the curve 
clockwise. Figure 68.2 illustrates these four points for two different curves; the triangle 
marks the apex, the square marks the peak, and the circles mark the endpoints. 




Figure 68.2 Defining curves 



AddEccentricCurve: proc[ 
h: Handle, 
box: Box, 

eccentricCurveProps: EccentricCurveProps]; 

EccentricCurveProps: TYPE ■ long pointer to 
EccentricCurvePropsRec; 
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EccentrkCurvePropsRec: TYPE ■ record [ 
brush: Brush, 
lineEndNW: LineEnd, 
lineEndSE: LineEnd, 
lineEndHeadNW: UneEndHead, 
lin«EndHeadSE: LineEndHead, 
direction: UneDirection, 
piaceNW, placeApex, piaceSE: Place* 
eccentricity: cardinal 
]; 

AddEccentricCurve is just like AddCurve except that the curve is specified by its 
endpoints, apex, and eccentricity, rather than by endpoints, apex and peak. 

eccentricity is a fraction represented as a cardinal with the decimal point to the left of the 
bits rather than to the right. This allows the highest possible precision for eccentricities 
between 0 and 1. 

This procedure can raise the error notEditable or documentFuil. Note that all of the types 
for eccentric curves are currently in GraphicsinterchangeExtraDefs. 

AddEllipse: proc [ 
h: Handle, 
box: Box, 

eilipseProps: EilipseProps]; 

EliipseProps: TYPE ■ long pointer to EilipsePropsRec; 
EIlipsePropsRec: type ■ record [ 

brush: Brush, 

shading: Shading]; 

Shading: type ■ record [gray: Gray, textures: Textures]; 

Gray: type ■ machine depenoent{ 

none(0), gray25(1), gray 50(2), gray 75(3), biaci((4), (15)}; 

Textures: type ■ packedarray Texture of boolean; 

Texture: type ■ machine depenoent{ 

vertical(O), horizontai(l), nwse(2)tf swne(3), 
poikadot(4),(11)}; 

AddEllipse adds an ellipse to the specified graphics container, box.dims determine the size 
and shape of the ellipse; box.place determines its location relative to the frame. 

Witliin the EliipseProps, brush describes the ellipses' border, and shading describes its 
interior. The shading of the interior can be 25%, 50%, or 75% gray or solid black; the 
texture can be horizontal, vertical, or diagonal lines, or dots. 

AddLlne: proc [h: Handle, box: Box, lineProps: LineProps]; 
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LineProps: TYPE ■ long pointer to LinePropsRec; 
LinePropsRec: type ■ record [ 

brush: Brush, 

iineEndNW: LineEndr 

lineEndSE: LineEndr 

lin«EndHeadNW: LineEndHead, 

lineEndHeadSE: UneEndHead, 

direction: LineOirection 

1; 

AddLina adds a line to the graphics container at location box.place. LineProps are all as 
described above for curves. 

AddPoint: proc [h: Handle, box: Box, pointProps: PointProps]; 

PointProps: type ■ long pointer to PointPropsRec; 

PointPropsRec: type ■ record [ 
wthbrush: CARDINAL, 
pointStyie: PointStyie <- round, 
pointFiil: PointFiil <- solid]; 

PointFiil: TYPE ■ machine dependent {soiid(0),holiow(1)» (255)}; 

PointStyie: type • machine dependent{ 

round(0), square(1 ), triangle(2), cross(3), (255)}; 

AddPoint adds the point described by pointProps to the graphics container h at location 
box.place. wthbrush is in micas. 

AddRectangie: PROC [ 
h: Handle, 
box: Box, 

rectangleProps: RectangieProps] 

RectangleProps: TYPE ■ long pointer to RectanglePropsRec; 

RectangiePropsRec: type ■ record [ 
brush: Brush, 
shading: Shading]; 

AddRectangie adds the rectangle specified by box.dims to the graphics container at the 
location box.place. Rectangle properties are as described above for ellipses. 

AddTriangle: proc [ 
h: Handle, 
box: Box, 

triangleProps: TriangieProps]; 
TriangieProps: TYPE ■ long pointer to TrianglePropsRec; 



68-8 



Viewpoint Programmer's Manual 



68 



TrianglePropsRec: type ■ record [ 
brush: Brush, 
shading: Shading, 
piacelt piace2, place3: Place 
1; 

AddTriangie adds a triangle to tlie graphics conainter at location box.place. brush and 
shading are as described for ellipses; placel, place2, and piaceS are the comers of the 
triangle, relative to box. 

Frame objects 

The following Add* routines add various types of frame objects to the graphics container. 
Each of these routines has a parameter of type FrameProps that describes the frame, and 
want*CaptionHandie parameters that determine the captions for that frame. These 
parameters are as described in section 68.2.1.1, StartGraphicsFrame. 

AddBitmap: PROC[ 
h: Handia, 
box: Box, 

bitmapProps: BitmapProps, 
frameProps: FrameProps, 
wantTopCaptionHandla, 
wantBottomCaptionHandle, 
wantLeftCaptionHandle, 
wantRightCaptionHandle: BOOLEAN 4- false] 

RETURNS [ 

topCaption, bottomCaption, 

leftCaption, rightCaption: Oocint«r€hangeo«f$.Caption],' 

bitmapProps describes a bitmap frame. bitmapProps largely correspond to the properties 
that the user sees in the property sheet. 

BitmapProps: TYPE ■ long pointer to BitmapPropsRec; 
BitmapPropsRec: type ■ record [ 

opaque: boolean, 

xOffset, yOffset: integer, 

printFile: xstring.ReaderBody <- xstring.nutlReaderBody, 
displaySource: BmOisplay]; 

opaque specifies whether the bitamp is opaque or transparent. xOffset and yOffset 
control the position of the bitmap within the bitmap frame. Setting both to 0 will position 
the bitmap flush in the upper left-hand comer. These values are in pixels. 

printFile is the source for the bitmap to print. This is usually the same as the display 
source, but the client may specify a file name as an alternate print source if desired. 

BmOispiay: type ■ record [ 
select type: *from 

internal ■ > [bm: long pointer to BitmapData], 
file ■ > [name: xstring.ReaderBody]. 
endcase]; 
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The source for the displayed bitmap is ia one of two locations: either internal (the bits are 
copied into the document), or in a file on the desktop. 

BitmapData: type ■ record! 

signature: integer <- bmSignature, 
xScale: int«rpr«st.Rationalt 
yScale: int«rpr«ss.Rational, 
xOim: caroinau 
yDim: caroinau 

bpl: CAROINAU 

pages: NSS«gm«nt.PageCount, 

bits: PACKED ARRAY [CO) OP Environni«iit.Byte]; 

bmSignature: integer ■ 23456; 

The actual bitmap is described by a BitmapData record, signature is a validity check for 
the bitmap. If a bitmap signature is anything but bmSignature, the implementation will 
not recognize it as a valid bitmap. 

xScale and yScaie specify the bitmap scale. At present, the only scale that is supported is 
72 spots per inch, so the client should always set xScaie and yScaie to[254, 720,000]. ( The 
default unit for an int«r|ir«tt.Rational is meters; converting inches to meters yields 720,000 
spots per 254 meters, since 1 inch = 2.54 cms.) 

xDim and yOim describe the size of the bitmap, bpt is the width of the bitmap, rounded to 
the nearest word boundary. The client should ensure that the bitmap's x dimension is 
equal to bpl. 

pages is the number of pages that the bitmap occupies, and bits is the actual bitmap. 

AddFormFieid: proc [ 
h: Handle, 
box: Box, 

fieldProps: FieldProps, 

frameProps: FrameProps, 

paraProps: ParaPropfDirfs.ReadonlyProps <~ NIU 

fontProps: PontPropso«fs.ReadonlyProps «- NIL, 

wantFieldHandie, 

wantTopCaptionHandle, 

wantBottomCaptionHandle, 

wantLeftCaptionHandle, 

wantRlghtCaptionHandle: boolean «- false] 

returns! 

field: Oo<lnttr€hang«D«fs.Field, 

topCaption, bottomCaption, leftCaption, 

rightCaptlon: Dodnt«rchang«D«fs.Caption]; 



Viewpoint Programmer's Manual 



68 



FieidProps: TYPE ■ long pointer to FieldPropsRecord; 
FieldPropsRecord: type ■ record [ 

language: MuitiNationai.Language, 

length: cardinal <- 0, 

required: boolean <- false, 

ski'plf : SkiplfChoiceType, 

stopOnSkip: boolean 4- false, 

type: FieidChoiceType <-any, 

fillinRule, 

description, 

format, 

name, 

range, 

skipif Field: xstring.Reader 4-NiL, 

f iillnRuleRuns: FontRunD«fs.FontRuns «- trash , 

1; 

SkiplfChoiceType: TYPE ■ machine dependent { 
empty, notEmpty, never, always}; 

FieldChoiceType: type ■ machine dependent { 
any, text, amount, date}; 

AddFormField adds the speciiied field to h at the location box. 

fieidProp^ desribes the properties of the field; paraProps and fontProps describe 
properties for the paragraph character within the field. 

In FieidProps, language is the language for the field; this controls the format of the date, 
length is the lengtii of the field, in characters. 

required specifies whether the field is required; skipif and stopOnSkIp determine how the 
field reacts to the SKIP key. type indicates the type of data that can be in the field. 

fililnRuie defines the fiUin rule for the field, description, format, and name describe the 
field. If the client defaults the name property when calling AddFormField, AddFormField 
wUl generate a new, unique name for the field. 

If the client specifies wantFieldHandle s true, AddFormField will return a 
Do<int«rch«ng«D«fs.Field; the client must eventually free this Held with a call to 
Docint«rchang«o«fs.ReleaseField. To add information to the field, the client should use the 
facilities of DoclnterchangeDefs. 

Addlmage: proc [ 
h: Handle, 
box: Box, 

imageProps: ImageProps, 

frameProps: FrameProps, 

wantTopCaptionHandle, 

wantBottomCaptionHandle, 

wantLeftCaptionHandle, 

wantRightCaptionHandle: boolean *- false] 
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RETURNS [ 

topCaption, bottomCaption, 

leftCaption, rightCaption: Docint«rchangao«fs.Cafition]; 

ImageProps: TYPE ■ long pointer to I magePropsRec; 
ImagaPropsRec: type ■ record [ 
name: xstring.Reader 4- nil]; 

Addlmage adds an image frame to the specified graphics container. 

AddTextFrame: proc ( 
h: Handle, 
box: Box, 

frameProps: FrameProps, 

wantTextHandle, 

wantTopCaptionHandle, 

wantBottomCaptionHandle, 

wantLeftCaptionHandie, 

wantRightCaptionHandle: boolean 4- false] 

returns! 

text: Text, topCaption, bottomCaption, 
leftCaption, rightCaption: Docifit«r€hangeD«fs.Caption]; 

Text: TYPE ■ LONG POINTER TO TextObject; - 

TextObject: type; 

AddTextFrame adds a text frame to the specified graphics container. If the client specifies 
wantTextHandie s true, it will return a handle to a text frame. The client can then call 
any of the Append*ToText routines below to add text to the text frame, and then must 
eventually call ReleaseText (see section 68.2.1.3) to free it. 

AppendCharToText: proc [ 
to: Text, 

char: xchar.Character, 

fontProps: FontPropsD«fs.ReadoniyProps 4- nil, 
nToAppend: cardinal 4- 1]; 

AppendFleldToText: proc [ 
to: Text, 

fieldProps: FieldProps, 
fontProps: FonfPropsD«fs.ReadonlyProps <-nil] 
returns [field: Docint«rdiang«D«fs.Fieid]; 

AppendNewParagraphToText: proc [ 
to: Text, 

paraProps: ParaPrQpsDefs.ReadonlyProps 4- nil, 
fontProps: FontPropsOafs.ReadoniyProps <~nil, 
nToAppend: cardinal 4- 1]; 
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AppendTextToText: proc [ 
to: Text, 

text: xstring.Reader, 

textEndContext: xstring.Context, 

fontProps: FontPropso«fs.ReadoniyProps <- nil]; 

Adding to a cusp button 

The foUoMring routines allow the client to add textual information to a cusp button 
program. 

AppendCharToButtonProgram: proc [ 
to: ButtonProgram, 
char: xchar.Character, 

fontProps: FontPropsD«fs.ReadonlyProps nil, 
nToAppend: cardinal ♦-I]; 

Add a character to the button program. nToAppend is the number of copies of the 
character to be added; fontProps are the properties of the character. 

AppendNewParagraphToButtonProgram: proc [ 
to: ButtonProgram, 

paraProps: ParaPropso«fs.ReadoniyProps 4- nil, 
fontProps: FofrtPropsO«fs.ReadonlyProps 4- nil, 
nToAppend: cardinal 4- 1]; 

Add a new paragraph character with specified properties to the button program. 

AppendTextToButtonProgram: proc [ 
to: ButtonProgram, 
text: xstring.Reader, 
textEndContext: xstring.Context. 
fontProps: FontPropso«f$.ReadoniyProps <- nil]; 

Add a string with specified properties to button program. For efficiency, the client should 
include textEndContext if known. 

Adding miseellaneoua graphics 

AddOther: PROC [ 
h: Handle, 
box: Box, 

instance: inttanc«o«fs.lnstance]; 

AddOther is provided to allow addition of charts and other as yet imdefined objects. For 
information on charts, see ChartDatalnstailDefs. 
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68.2.1^ Release routines 

ReleaseText: proc [textPtr: long pointer to Text]; 

ReleaseButtonProgram: proc [ 

bpPtr: LONG POINTER TO ButtonProgram]; 

ReleaseText and ReleaseButtonProgram release handles obtained from AddText and 
AddButtonProgram. Like Mesa's free operator, these routines take a pointer to the object 
to be freed, and set the handle itself to nil. Thus, after a call to ReleaseText, text will be nil; 
after a call to ReleaseButtonProgram, ButtonProgram will be nil. 

68.2.1.4 Finish routines 

When everything has been added to a graphics container, the client should call a Finish 
routine. 

FinlshButton: proc [bfh: Handle]; 

FinlshCluster: proc [ch: Handle]; 

FinishGraphics: proc [h: Handle] returns [ 
graphics: instanc«o«fs.lnstance]; 

FinishGraphicsFrame: proc [gfh: Handle]; 

bfh, ch, h, and gfh are the handles obtained from the cfnresponding Start routines. The 
client will typically pass the instanceocfs-lnstance returned by FinishGraphics to 
Docint«rdtang«oefs.AppendAnchoredFrame. 

68.2.2 Reading graphics 

To read the contents of a graphics frame, the client should call Enumerate. Enumerate 
takes as parameters a graphics container and a list of call back procedures, one for each of 
the kinds of items that might be in the graphics container. Enumerate will proceed 
through the graphics container, calling the appropriate procedure for each item that it 
encounters. 

Each enumeration procedure takes parameters that describe the properties of the object. 
These properties are temporary, and will be destroyed after the client procedure returns. 
If the client wishes to save any of these properties, it must explicitly copy them. 

Client EnumProcs do not need to call any Release* routines on anything passed them as a 
parameter. The Enumerator always releases containers after calling each EnumProc. 

In the case of a cusp button, cluster, or nested graphics frame, the client can recursively 
call Enumerate to get the contents of the nested frame. There are also related 
enumerators, EnumerateText and EnumerateButtonProgram, that enumerate the 
contents of a text frame and a cusp button, respectively. 
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Enumerate: proc [ 

doc: Oodnt«rchang«D«fs.Doc, 
graphicsContamer:instanceO«fs.lnstance, 
procs: EnumProcs, 
clientOata: long pointer nil] 
RETURNS [dataSkipped: boolean]; 

EnumProcs: TYPE ■ lon<3 pointer to EnumProcsRecord; 

EnumProcsRecord: type ■ record C 
bitmapProc: BitmapProc<-NiL, 
buttonProc: ButtonProc niu 
clusterProc: CtusterProc4-NiL, 
curveProc: CurveProc 4-NiL, 
ellipseProc: EilipseProc4-NiL, 
formFieldProc: FormFieldProc«-NiL, 
frameProc: FrameProc4-NiL, 
imageProc: ImageProc <- nil, 
lineProc: LineProc<-NiL, 
otherProc: OtherProc nil, 
pointProc: PointProc <-nil, 
rectangleProc: RectangleProc4-NiL, 
textFrameProc: TextFrameProc <-nil, 
triangleProc: TriangieProc 4~nil]; 

BitmapProc: type ■ proc [ 
ciientData: LONG pointer, 
box: Box, 

bitmapProps: BitmapProps, 
frameProps: FrameProps] 

RETURNS [stop: BOOLEAN FALSE]; 

ButtonProc: type • proc [ 
clientData: long pointer, 
graphicsContainer: instanc«o«ft.lnstance, 
box: Box, 

buttonProps: ButtonProps, 
frameProps: FrameProps, 
buttonProgram: ButtonProgram] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

ClusterProc: type ■ proc [ 
clientData: long pointer, 
graphicsContainer: iiittanc«D«ft.lnstance, 
box: Box] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

CurveProc: type ■ proc ( 
clientData: long pointer, 
box: Box, 

curveProps: CurveProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 
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EilipseProc: type ■ proc [ 
ciientData: long pointer, 
box: Box, 

ellipseProps: EilipseProps] 

RETURNS [stop: BOOLEAN ^ FALSE]; 



FormFieldProc: type ■ proc [ 
ciientData: long pointer, 
box: Box, 

fieidProps: FleldProps, 
frameProps: FrameProps, 
paraProps: ParaPropsOefs.ReadonlyProps, 
fontProps: FoiitPropso«fs.ReadoniyProps, 

content: Dodnt«rchang«0«fs.Fleid] 
RETURNS [stop: BOOLEAN 4- FALSE]; 

FrameProc: type ■ proc [ 
ciientData : long pointer, 
graphicsContainer: instanceOefs.lnstance, 
box: Box, 

frameProps: FrameProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

ImageProc: type ■ proc [ 
ciientData: LONG POINTER, 
ix>x: Box, imageProps:,lmageProps, 
frameProps: FrameProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

LineProc: type ■ proc [ 
ciientData: long pointer, 
box: Box, 

iineProps: LineProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

OtiierProc: type ■ proc [ 
ciientData: long pointer, 
box: Box, 

instance: !nstanc«D«fs.lnstance] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

PointProc: type ■ proc [ 
ciientData: long pointer, 
box: Box, 

pointProps: PointProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

RectangieProc: type ■ proc [ 
ciientData: LONG POINTER, 
box: Box, 

rectangieProps: RectangieProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 
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TextFrameProc: type » proc [ 
clientData: long pointer, 
box: Box, 

frameProps: FramaProps, 
contant: Text] 

RETURNS (stop: BOOLEAN 4- FALSE]; 

TriangiaProc: type ■ proc [ 
ciiantData: long pointer, 
box: Box, 

triangieProps: TriangleProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

Enumerating text frames 

EnumarataText: proc [ 
text: Text, 

procs: TextEnumProcs, 
, ciiantData: long pointer nil] 
RETURNS [dataSkipped: boolean]; 

TextEnumProcs: TYPE ■ long pointer to TextEnumProcsRecord; 

TextEnumProcsRecord: type ■ record [ 

f ieldProc: Dodnt«rchangeO«fs.FieidProc <-NIL, 

newParagraphProc: 

oociiit«rciMng«o«fs.NewParagraphProc 4-nil, 
taxtProc: oocint«rchang«o«fs.TaxtProc 4-nil]; 

EnumerateText enumerates tlie contents of a text frame, calling the client-supplied 
EnumProcs as appropriate. 

Enumerating button programs 

EnumarateButtonProgram: proc [ 
buttonProgram: ButtonProgram, 
procs: ButtonProgramEnumProcs, 
ciiantData: long pointers nil] 
RETURNS [dataSicippad: boolean]; 

ButtonProgramEnumProcs: TYPE ■ long pointer to 
ButtonProgramEnumProcsRacord ; 

ButtonProgramEnumProcsRecord: TYPE ■ record [ 
nawParagraphProc: 

Doclnt«rchang«Oefs.NewParagraphProc 4- NIL, 
taxtProc: Dodnt«rchang«D«fs.TaxtProc 4-nil]; 

EnumarateButtonProgram enumerates the contents of a cusp button program, calling the 
client-supplied EnumProcs as appropriate. 
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08^3 Errors 

ErrorType: type ■ {notEditable, documentFuil}; 
Error: signal [type: ErrorType]; 

Note that Error and ErrorType are currently in GraphicslnterchangeExtraOefs. Error is 
not presently implemented and is anticipated that all routines may raise them. 
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Text: TYPE 

TextEnumProcs: type 
TextEnumProcsRecord: type 
TextFrameProc: type 
TextObject: type 
Texture: type 
Textures: type 
TriangleProc: type 
TriangieProps: type 8 
TriangiePropsRec: type 9 
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69.1 Overview 

InstanceDefs is an auxiliary interface used in conjunction with OoclnterchangeOefs, 
GraphicslnterchangeOefs, TabielntarchangeOefs, and ChartDatalnstallDefs. 

69.2 Interface Items 

The primary type in this interface is the Instance, which represents an object in a 
document. For example. Instances can represent the content of graphics frames, 
documents, or tables. 

Instance: me <■ record [Izn: Izn, rref : Rref]; 

lzn:TYPE ■ RECORD [UNSPeOFiEO]; 

Rref: type ■ Base relative pointer; 
Base: TYPE ■ long base poimter; 

An Instance contains Izn ("instance zone") which is a handle to a run time storage space 
that holds various objects in a document, and rref, which is a relative pointer to a 
particular Instance within the instance zone. The client does not need to know anything 
about the structure of an Instance; it just needs to be able to pass it as a parameter to 
various documents procedures. 

For example, to create an anchored graphics frame in a document, the client would use the 
facilities of GraphicslnterchangeDefs to obtain an Instance that represents the content of 
that graphics frame, and then call Docint«rchangeO«fs.AppendAnchoredFrame, passing in 
that Instance as the content parameter. The client never directly handles the instance, 
however. 

InstanceNil: Instance ■ [IznNll, rrefNil]; 
IznNil: Izn ■ loophole[nil]; 
rref Nil: Rref ■ loophole[0]; 
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instanceNii is a nil Instance, for convenience. 
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69.3 Index of Interface Items 

Item Page 

Base: type 1 

Instance: type 1 

instanceNil: Instance 1 

lin: TYPE 1 

iznNil: Izn 1 

Rref : type 1 

rrefNII: Rref 1 
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70.1 Overview 

ParaPropsOfif s includes the data types used to describe paragraph properties in ViewPoint 
documents. It does not contain any procedures; it is intended to be used in cozijunction 
with DoclnterchangeDefs. 

70.2 Interface Items 

The chief type in this interface is the PropsRecord, which describes the possible paragraph 
properties. 

Props: TYPE • LONG POINTER TO PropsRecord; 

ReadoniyProps: TYPE ■ long pointer TO readonly PropsRecord; 

PropsRecord: TYPE a RECORD [ 

basicProps: BasicPropsRecord <- trash, 
tabStops: TabStops ^ trash]; 

basicProps describes all standard paragraph properties (those on the Paragraph property 
sheet); tabStops describes the current tab settings (the information on the Tab Settings 
property sheet). 

The following sections describe the BasicPropsRecord and TabStops records in detail. 

70.2.1 BasicPropsRecord 

BasicProps: type ■ long pointer to BasicPropsRecord; 

ReadonlyBasicProps: TYPE ■ long pointer to readonly 
BasicPropsRecord; 

BasicPropsRecord: type ■ machine dependent record [ 
preLeading(0:0..1 5): cardinal <- trash, 
postLeading(1 :0..1S): cardinals trash, 
leftlndent(2:0..1 5): cardinal trash. 
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rightlndent(3:0..1 5): cardinal trash, 
lineHeight(4:0..15): cardinal trash, 
paraAlignfnent(5:0..1): ParaAiignment <- trash, 
justified(5:2..2): boolean trash, 
hyphenateci(5:3..3): boolean trash, 
lceepWithNextPara(5:4..4): boolean trash, 
language(5:5..12): MuitiNationai.Languag« ^ trash, 
$treakSuccession(5:13..13): StreakSuccession <- trash, 
unus€d5(5:14..15): packed array [14..15] of[0..1] 4-all[0], 
def aultTabStopSpacing(6:0..1 3): 

Def auitTabStopSpaci ng(0..1 6383] <- trash, 
def auitTabStopAlignm€nt(6: 14..1 5): 

TabStopAiignment trash 

]; 

preLeading and postLeading are the spacing before and after the paragraph respectively; 
these values are in units of 1/72 inch. 

laftlndent and rightlndent are the left and right paragraph margins; these values are in 
units of 1/72 inch. 

iineHeight is the default line height for the paragraph; this value is in units of 1/72 inch. 

ParaAlignment: type ■ machine dependent 
{left(0), centeKD* right(2)}; 

paraAlignment indicates the alignment of the paragraph relative to the containing text 
column or text block. 

justified when TRUE, causes the text in the paragraph to stretch to make a straight right 
edge. 

hyphenated indicates whiether the paragraph will be hypenated at the end of lines to 
improve justification. This parameter currently does nothing and should be set to false. 

keepWithNextPara indicates whether the paragraph should always be on the same page 
as the succeeding paragraph. 

language is the language for the paragraph; this information is used for formatting 
decimal tabs. It is also used when items are added to the paragraph (e.g., a field inherits 
the paragraph language when added to the paragraph). 

StreakSuccession: TYPE ■ machine dependent {ieftToRight(0), 
rightToLeft(1)}; 

StreakSuccession specifies whether a "streak" of characters should logically be read from 
left to right (e.g. English) or right to left (e.g. Hebrew). 

TabStopOffset: type ■ cardinal[0..16383]; 

DefauitTabStopSpacing: type ■ cardinal[0..16383]; 
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defauitTabStopSpacing is the default number of spaces between tabs. 

TabStopAiignment: type m machine dependent 
{l6ft(0), cantar(1)« right(2), decimai(3)}; 

defaultTabStopAilgnment is the default alignment for tabs: tabs can be relative to the left 
paragraph margin, the center of the paragraph, the right paragraph margin, or decimal 
points. 

70^ Tabs 

TabStops: type ■ long descriptor for array op TabStop; 

TabStop: type ■ machine dependent record [ 

dotLeadeKO: 0..0): boolean, 

spare(0: 1..1): boolean 4- false, 

tabStopOffS€t(0: 2..13): cardinal [0..7777B], 
- 4095 max 

tabStopAlignment(0: 14..15): TabStopAiignment]; 
tabStops describes the currently set tabs for the paragraph. 

dotLeader indicates whether the tab has leader dots. tabStopOffset indicates the location 
of the tab, relative to the paragraph margin. tabStopAlignment indicates the alignment of 
the tab. 

nTabsMax: cardinal ■ 100; 

nlabsMax is the maximum number of tabs that there can be in a paragraph. 
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70.3 Index of Interface Items 



Item Pago 

BasicProps: type 1 

BastcPropsRecord: type 1 

DefauitTabStopSpadng: type 2 
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ParaAlignment: type 2 
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PropsRecord: type 1 
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StreakSuccession: type 2 

TabStopAiignment: type 3 

TabStopOffset: type 2 

TabStop: type 3 

TabStops: type 3 
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71.1 Overview 

TabielnterchangeOefs allows clients to read the contents of a table, create a new table, or 
add information to an existing table. This interface should be used in coi^junction with 
DoclnterchangeOefs. 

A table is described by three sets of properties: table properties, column properties, and 
row properties. Table properties include the name of the table, a description of table 
headers and the number of columns and rows in the table; column properties include 
whether the columns are divided, and the alignment of text within the columns; and row 
properties include information about how the text is aligned within a given row. The 
actual content of a table is included with the row information. 

71.1.1 Table building 

To create a new table, the client should start by calling StartTable. This procedure takes 
table properties and column properties as parameters, and returns a table handle. Handle 
points to Object, which is a record that contains, along with table-related data, a pointer to 
the actual table content (See section 71.2.1.1 Diagram of Table Structure, Fig. 71.1). 
Initially, the row properties have default values and the table has no content; the client 
should initialize row properties and content after the call to StartTable. 

To add content to the table, the client can pass the table handle to Append Row, which 
adds new information to the table. When all of the rows have been added, the final step is 
to call FinlshTable, which creates the final structure for the table. Once the table is 
created, the client can pass this table to the procedures in DoclnterchangeOefs to append 
it to a document. 

FinlshTable returns an instancaO«fs.lnstanca for the table, which the client can pass to 
oocint«rchang«o«fs.AppendAnchoredFrame. 

To add information to an existing table, the client should call StartExistingTable instead of 
StartTable. This procedure also returns a table handle, which the client can then pass to 
AppendRow and FinlshTable. StartExistingTable takes an instanc«D«fs.lnstance as a 
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parameter; the client will typically call Tabi«Sei«ctiono«fs.TableFromSeie€tion to get the .0^^ 
currently selected table as a value of type instanc«o«fs.lnstance. 

71.1.2 Table reading 

To read the contents of a table, the client typically starts by calling Enumerate. 
Enumerate takes as arguments a table object (instanc«o«ff.lnstance) and a record of three 
call back procedures: a TableProc, a ColumnsProc, and a RowProc. 

Enumerate will call the TabieProc and the ColumnsProc once for a given table; these 
procedures obtain the table and column properties. Since the content of the table is stored 
with the rows, Enumerate will call the RowProc once for each row in the table. 

There is a also a procedure EnumerateSpecif icRows, which is just like Enumerate except 
that it enumerates a specific list of rows within a table rather than the entire table. 
EnumerateSpecif icRows will call the RowsProc once for each row in the specified range of 
rows. 

71.2 Interface Items 

71.2.1 Table building operations 

71.2.1.1 Creating a new table 

StartTabie: PROC[ 

doc: 0odnMrchang«O«f$.Doc, 

props: TableProps, 
c: Columninfo, 

invisibieRuiingUnes: boolean 4-true] 
RETURNS [h: Handle]; 

StartTabie creates a document table in doc. InvisibleRullngLlnes spectres whether the 
lines that form the table are visible, props describes the properties of the table itself; c 
describes the properties of the columns. The Handle that is returned contains a description 
of row properties and table content. 

The following sections describe TableProps, Columnlnfo, and Handles in detail. 

StartTabie can raise Error[documentFull] if the table and header row will not fit in the 
document. If StartTabie raises this error, the table cannot be added to the document due to 
lack of space. 

Table properties 

A TablePropsRec describes the properties of a table and its headers. 

TableProps: type ■ long pointer to TablePropsRec; 

TablePropsRec: type ■ record ( 
name: xstring.Reader 4-nil, 
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filiinByRow: boolean 4~true. 

fixedRows: boolean false, 

fixedColumns: boolean true, 

numberOfCoiumns: natural <-> 0, 

numberOf Rows: natural 0, 

visibldHeader: boolean true, 

repeatHeader: boolean true, 

borderLine: Line 4- [none, w1], 

dividarUne: Una [solid, w4], 

horizontalAiignmant: HaadarAlignmant 4- cantar, 

headarVerticaiAlignment: VarticalAiignmant ^ cantarad, 

topHaadarMargin, bottomHaadarMargin: natural]; 

nama is the name of the table. 

filiinByRow determines what happens when the user presses the next key. If filiinByRow 
is true, pressing the next key advances through the table one row at a time, and the table 
is expanded by rows. In this case, the number of columns is fixed and the number of rows 
can be either fixed or varying. filiinByRow ia false, then pressing the next key advances 
through the table one column at a time, and the table is expanded by columns. In this case, 
the number of rows is fixed and the number of columns can l>e either fixed or varying. 
fixedRows and fixedColumns indicate whether the user can change the number of rows 
and columns in the table. 

numberOfCoiumns and numbarOf Rows are used as hints for StartTabla. 

visiblaHaadar indicates whether there should be a visible header at the top of the table; 
rapeatHeadar indicates whether or not to repeat the header on every page if the table 
occupies multiple pages. 

ix>rdarLlne describes the table border (not the frame border), and dividerLlne describes the 
line between the header row and the rest of the table. In tables, a line is either solid or 
invisible; a solid line can have a width anywhere from one pixel to six pixels. 

Una: type ■ record [ 

iinastyla: Unestyla solid, 
linawidth: Linawldth <- w1 ]; 

Unastyla: TYPE ■ machine dependent {solid(0),nona<5)}; 

Unawidth: type ■ machine dependent {w1(0), w2(1), w3(2), w4(3}, w5(4), w6(5)}; 

horizontalAiignmant and haadarVarticalAlignmant specify the alignment of the text 
within a header. 

HaadarAlignmant: type - HorizontalAlignmantUaft.right]; 

HorizontalAiignmant: type ■ machine dependent {iaft(0),cantaKl)« right(2),dacimal(3)}; 
VarticalAiignmant: type ■ machine dependent {flushtop(0),cantarad(1),flushbottom(2)}; 
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topHeaderMargin and bottomHeaderMargin specify the amount of white space that 
should appear between above and below each header element. 



Column properties 

Coiumnlnfo: TYPE ■ lon<3 pointer to ColumninfoSeq; 

ColumnlnfoSeq: type ■ record! 

SEQUENCE length: cardinal of ColumnlnfoRec]; 

CoiumnlnfoRec: TYPE ■ record [ 

headerEntryRec: HeaderEntryRec <- 

name, description: xstring.Reader 4- NiU 

divided: boolean 4- false, 

subcolumns: NATURAL «- 2, 

repeating: boolean 4- false, 

sutKoiumnlnfo: G)lumnlnfo 4- nil, 

aiignment: HorizontalAlignment 4- center, 

tabOffset: natural 4-0, 

width: natural, 

leftlVlargin: natural, 

rightMargin: natural, 

type: Fieidtype 4-any, 

required: boolean 4- false, 

language: MuitiNationai.L^nguage, 

format: xstring.Reader 4- nil, 

stopOnSlcip: boolean 4- false, 

range: xstring.Reader <- nil, 

lengtii : natural 4- 0, 

slcipText: xstring.Reader 4~NiL, 

sicipChoice: SIcipChoices 4- empty, 

fillin: xstring.Reader 4-nil, 

filiinRuns: FontRunD«fs.FontRuns 4- nil, 

line: Line 4- [solid, w2] 

]; 

A ColumnlnfoSeq describes all the columns of a table; a ColumnlnfoRec describes one 
column in detail. Within a ColumnlnfoRec, the most complicated Held is a 
headerEntryRec; all of the other fields correspond directly to the fields on the property 
sheet that the user sees. The next section, discusses the header properties; and the section. 
Other column properties, discusses the remaining column properties. 

For a more complete description of any of these properties, see the user documentation. 

Coluipn header properties 

HeaderEntryRec: TYPE ■ record [ 
subHeaders: Headerlnfo 4- nil, 
reader: xstring.Reader 4- nil, 
readerHasNewPars: boolean 4- false, 
alignment: HeaderAlignment 4- center. 
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line: Line <- [solid, w2], 
singleLineHint: boolean <- false, 
stringEndContext: xstringXcntext 4~ 

xstring.unl(nownContext, 
font: FontPropsD«fs.Props <-NIL, 
paraProps: ParaPropso«fs.Props 4- nil]; 



A HeaderEntryRec describes the textual content of a column header. Header text can 
contain only one font and one set of paragraph properties per column header, 

subHeader describes the headers for each of the subcolumns. This Held is only interesting 
if the column is divided. subHeader points to a sequence that contains a HeaderEntryRec 
for each subcolumn. Each subcolumn may in turn be sulxlivided, in which case that 
subcolumn's HeaderEntryRec subHeader field would point to another sequence. 



Table 



HeaderEntryRec for table : 
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Figure 7 1 . 1 Table and HeaderEntryRec for table 



Headerlnfo: TYPE ■ long pointer TO HeaderlnfoSeq; 

HeaderlnfoSeq: type ■ recoro[sequence length: cardinal of HeaderEntryRec]; 

reader is the actual contents of the header string. readerHasNewPars indicates whether 
there are any new paragraph characters in the header text. 
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alignment describes the alignment of the text within the header. ,.0% 

line describes the properties of line that divides the header from subheaders; line is only 
visible if the column is subdivided. 

singleLineHint is a hint that the header only contains one line of text; this makes the code 
slightly faster by simplifying the calculation of header size. 

stringEndContext is a hint that the client should fill in if the information is known. 

font and paraProps describe the textual properties. If font is defaulted, the system default 
font will he used. paraProps.basicProps.paraAlignment is ignored, since the information it 
provides is superceded by alignment. 

Other column properties 

name and description are the name and description of the table as it appears in the 
property sheet. 

divided specifies whether the columns can be divided, subcolumns is the number of 
subcolumns; repeating indicates that subcolumns can have subrows, and subcolumninfo 
is the recursive description of the subcolumns. subcolumns, repeating, and 
subcolumninfo are ignored if divided s FAL5E. 

alignmentdescribesthealignmentof the text within a column. Jii| 

tabOffset specifies where the tabs should be set, relative to the margin. tabOffset only 
applies if alignment s decimal; it is in micas. 

width is the width of the column; leftMargin and rightMargin are .the margins for the 
colunm. These values are also in micas. 

type indicates the type of content that will appear in a column. 

Fieidtype: TYPE « machine dependent {any(0),text(1)t 
amount(2), date(3)}; 

In order to be valid content field must contain textual characters; date must contain 
dates; amount must contain numeric characters and any can contain anything. No 
checking is performed until UPDATE FIELDS is invoked. 

required indicates that the entry is required, and that the user must fill it in before 
proceeding to another entry in the table. 

language affects the format of date and amount fields. It is used when items are added to 
the paragraph (e.g., a field inherits the paragraph language when added to the 
paragraph). 

format allows the user to define a format to which the data in the table must conform. 

stopOnSkip When the user presses SKIP, the skipping action shoudl stop at the entry that 
has this option. 
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range is used to define a specific i^uige of acceptable entries. Once defined, any entry not 
within the defined range is not acceptable. See the user documentation for information on 
how ranges are defined. 

length allows the user to define the maxiumum number of characters that will be accepted 
in the column entries. 

skipText and skipChoke defines the conditions under which an area may be skipped when 
the user presses NEXT. See the user docimientation for more detail. 

SkipChoices: typi ■ machine DEPENoeNT {empty(O), notEmpty(l), neverSkip(2), 
aiwaysSkip(3)}; 

SkipChoices enumerates the ways of handling the SKIP key. 

f illin and f illinRuns describe the fill-in rules for completing the table. 

line describes the properties of vertical line to right of column. 

Return values 

StartTable returns a handle: 
Handle: TYPE ■ long pointer to Object; 
Object: TYPE ■ record [ 

zone: UNCOUNTED ZONE, 

table: instanc«o«fs.lnstance, 
tabieHeight: long integer, 
tableWldth: long integer, 
rc: RowContent, 
private: array (0..0) op word]; 

zone is the zone from which dynamic storage specific to this operation is allocated, table 
is the table itself. 

tabieHeight is initially equal to the height of the header row and is updated after each call 
to AppendRow. tabieHeight and tableWldth are in micas, rc represents the actual 
content of the table; rc is owned by the implementation. 

RowContent: type ■ long pointer to RowContentSeq; 
RowContentSeq: type ■ record! 

topMargin, bottomMargin: natural, 

line: Line [solid, w2], 

verticalAlignment: VerticalAllgnment 4-flushtop, 
rowdata: sequence length: cardinal of RowEntryRec]; 

RowContentSeq describes row properties and content. The margins are the row margins; 
line is the properties of the line separating the rows. verticalAlignment specifies the 
alignment of text within a row. rowdata describes the content. 
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RowEntryRec: TYPE ■ RECORD [ jmi 
subRows: SubRows *- nil, 
reader: xstring.Reader «- nil, 
readerHasNewPars: boolean <- false, 
alignment: HorizontalAlignment center, 
tabOffset: natural 4-0, 
singieLineHint: boolean 4- false, 
stringEndContext: xstringXontext 4- 

xstring.unknownContext» 
font: PontProiMOtfs.Props 4- nil, 
paraProps: ParaPropso«fs.Props 4-nil]; 

A RowEntryRec describes the textual content of a given row entry. Note that the content of 
a given row element is restricted to one font and one set of paragraph properties. 

SubRows: TYPE ■ long pointer to SubRowsRec; 
SubRowsRec: type ■ record[ 
length: cardinal, 

rows: sequence maxLength: cardinal of RowContent]; 

SubRowsRec describes subrow properties and content. If subRows is non-NiL, then the rest 
of the RowEntryRec record is unused, since the information will be in the individual 
subrow records. 



Note that subrows may only exist if the parent column is divided. 
The remaining fields are as described for header properties. 

71^1.2 Opening an existing table 

StartExistingTable: proc[ 
table: instancaOefsJnstance, 
hi: Headerinfo 4-nil, 
rowPropsSource: natural 4- 0, 
deleteExistingRows: boolean 4- true, 
numberOf RowsHint: natural 4- 0] 
RETURNS [h: Handle]; 



StartExistingTable sets things up to append rows to an existing table, table is the table 
object. The table passed in to StartExistingTable is often obtained from a call to 
Tabi«s«i«ctionOefs.TableFromSelectlon, which returns the current selection as a table. 

hi describes the desired properties for the table headers. If lii s nil then the existing 
column headers are used. 

rowPropsSource is the index of a row in the table; this is the row from which the default 
properties should be taken; the rows are numbered from [0..n].The horizontal alignment 
for each entry is taken from first new paragraph character in corresponding element of 
first row. jiilli 
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deleteExistingRows indicates whether the implementation should delete the existing 
contents of the table before adding new information. numberOfRowsHint is a hint about 
the number of rows that the table will contain; this is for efficiency purposes. 

Like StartTable, StartExistingTable returns a Handle, which the client can then pass to 
AppendRow. 

This procedure will raise Error[tableNotEditable] if the document is read-only. 

71.2.1.3 Appending rows 

AppendRow: proc [h: Handle, rc: RowContent]; 

AppendRow adds the cow desqibed by rc to the table described by h. Typically, h will be a 
handle obtained from either StartTabie or StartExistingTable. 

RowContent is as described in section 71.2.1.1, return values for StartTabie. 

This procedure can raise Error(documentFull] if this row will not fit in document. If this 
error occurs, clients are expected to continue the error and then make a call to FInishTable. 

71.2.1.4 Finisliingatable 

FInishTable: PR0C[h: Handle] returns [ 
table: instanceo«fs.lnstance, 
tableWidth, tableHeight: long integer]; 

The client should call FInishTable when it is throu^ editing a table. The table that is 
returned is intended to be passed as the content argument to 
Docint«rchang«D«fs.AppendFrame. This operation deletes h.zone. tableWidth and 
tableHelght are in micas. 

FInishTable can raise Error(documentFull] if no rows were added and the single blank row 
added overflows the document. Clients may either RESUME (which results in a return value 
of instanc«D«fs.instanceNll) or continue (in this case the client must not reference h further 
and should assume that table is InstanceNll). 

71.2.1.5 Miscellaneous utilities 

MaxTableElements: prqc returns [natural]; 

This procedure returns the maximum size of the table, allowing clients to be smarter 
about large tables. 

DefaultFontProps: proc [font: PontPropso«fs.Props]; 
DefaultParaProps: proc [para: ParaPropsOflfs.Props]; 

These procedures take a properties record and fill in reasonable default values. 
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71.2.2 Table reading operations 

Enumerate: proc [ 

table: lnstan€eDefs.lnstance, 
procs: EnumProcs, 
clientData: long pointer <- nil]; 

EnumProcs: TYPE ■ long pointer to EnumProcsRec; 
EnumProcsRec: TYPE > record [ 

tabieProc: TabieProc 4-~nil« 

columnsProc: ColumnsProc ^-nil, 

rowProc: RowProc4-NiL]; 

To parse the contents of a table, clients call Enumerate or EnumerateSpecificRows. 
Enumerate takes as parameters a table handle and a record of callback procedures: one for 
table properties, one for column properties, and one for row properties. 

TableProc: TYPE ■ proc[ 

dientOata: long pointer, props: TabieProps] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

ColumnsProc: TYPE ■ proc[ 

clientData: long pointer, columns: Columnlnfo] 

RETURNS [stop: BOOLEAN 4- FALSE]; 



RowProc:TYPE ■ PROC[ 

clientData: long pointer, content: RowContent] 

RETURNS [stop: BOOLEAN 4- FALSE]; 

Enumerate calls the TableProc and the ColumsnProc once, passing in the appropriate 
property information. Because the content of the table is stored with the rows. Enumerate 
calls the rowProc once for each row in the table. 

Each of these callback procedures has a boolean return value. If stop is ever true, then the 
enumeration will stop. 

EnumerateSpecificRows: procT 
tr: TableRows, 
procs: EnumProcs, 
clientData: long pointer 4- nil]; 

TableRows: type ■ record [ 

table, firstRow, lastRow: instanc«Defs.lnstance]; 

EnumerateSpecificRows describes a certain subset of rows in a table. As with Enumerate, 
the tableProc and the columnsProc will each be called once to describe the appropriate 
properties; the column information will describe the columns intersecting the described 
rows. The RowProc will be called once for each row in [f irstRow..iastRow]. 

tabieRowsNII: TableRows ■ 
[instanc«o«fs.instanceNil, 
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instanceDttfsJnstanceNil, 
instanc«o«fs.instahceNil]; 

tableRowsNil specifies a default for TableRows. tableRowsNil is what you get if a table is 
not selected in a call to EnumericSpecif icRows. 



71.2^ Diagram of table structure 

Figure 71.2 is a diagram of a table structure. RowContent is a pointer to 
RowContentSeq; table is a record that contains two pointers to the actual instance of the 
table. (Note that table itself is not a pointer.) 
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Figure 71 .2 Diagram of Table Structure 
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71^4 Errors 

Error: signal [type: ErrorType]; 

ErrorType: type « {tableNotEditable, documentFull, tabieTooWide, tableTooTall, 
tableHeaderTooTai 1}; 

tableNotEditable StartExistingTable will raise this error if the client asks to 
open a read-only table. 

documentFuil StartTable will raise this error if there is not enough room 
for the initial table and its headers. 

AppendRow will raise this error if the client asks to append 
a new row and there is not enough room. 

FinishTabie will raise this error if the client tries to create a 
table with only one row (i.e., without any calls to 
AppendRow), and there is not enough room. 

tableTooWida StartTable will raise this error if the specified table is too 
wide to fit in the document. 

tabieTooTali AppendRow will raise this error if the specified table is too 

tall to fit in the document. jflli 

tableHeaderTooTail StartTable will raise this error if the specified headers are 
too tall. 



71.3 Usage/Examples 

Here is an example of a basic program that runs from the Attention Menu. It registers two 
commands: Make Table, which creates a new document with a table, and Add To Table, 
which adds four new rows to the selected table. 

tableWldth: cardinal ■ 1600; -micas 

headerMargin: cardinal ■ 35*9; -micas; margin should be 9 -pixels, so convert to micas 
by multipying by 35 
rowMargm: cardinal ■ 100; 

< < Create table inside doe with specified number of rows and columns. The content will 

be the string "abc. "> > 

BuildSimpleTabie: procC 

doc: Docintar€hang«Dtfs.Doc, rows, columns: cardinal] 
RETURNS [table: instanc«D«fs.f nstance 4- inttanc«D«fs.lnstanceN]i] 
-{ 

h: Tabl«lnt«rchang«D«fs.Handle; 
contentStrIng: xstring.ReaderBody 4- 

xstring.FromSTRING(''abc'*L]; 
c: Tablelnt«rchang«Defs.Columninfo 4- 

H«ap.systemZone.NEW( 

Tabl«int«r<hangeO«fs.ColumninfoSeq[columns] 4- trash]; 
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FOR i: CARDINAL IN [O..coiumns) 00 

c[i] 4- [leftMargin: 0, width: tableWidth, 

rightMargin: 0, language: USEngiish] 

ENOLOOP; 

props: Tabi«iiit«rchang«o«fs.TabiePropsRec 4- [ 
numberOKolumns: cotumns, 
numberOfRows: rows* 
visibleHeader: true, 
topHeaderMargin: headerMargin, 
bottomHeaderMargin: headerMargin]; 

"Start creating table 

h 4-T«bltlnt«r€hang«Otfs.StartTable[doc, ©props, c, false]; 
H«ap.systemZone.FREE{@c]}; 

-set row props and content 
h.rctopMargin rowMargin; 
h.rc.bottomMargin rowMargin; 
FOR i: cardinal in [O..rows) DO 

FOR j: CARDINAL IN [Ccolumns) 00 
h.rctil 4- [ 

reader: ©contentString, 
alignment: center, 
singieLineHint: true, 
font: NR.] 
endloop; 

"^mm^ Tabl«int«rchangeD«fs.AppendRow[h, h.rc]; 

endloop; 

RETURN [Tabi«ifit«r<hang«Dafs.FinishTable(h].table] 

}; 
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71.4 Index of Interface Items 
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72.1 Overview 

TabieSeiectionO«fs provides procedures to obtain the current selection as a table, or a 
selection of rows within a table. This interface is meant to be used in conjunction with 
TableinterchangeDefs. 

72.2 Interface Items 

TabieFromSelection: proc returns [instanc«Defs.lnstance]; 

TabieFromSelection returns the current selection as an object of type instanceO«fs.instance. 
The client will typically pass this value to Tabl«int«rchang«o«fs.StartExistingTable. 

TableRowsFromSelection: proc 

RETURNS [tr: Tabi«lnt«rchang«0«fs.TableROVVS]; 

TabieRowsFromSeiection returns the current selection as a series of rows in a table. The 
client will typically pass this value as a parameter to 
Tai>i«intarchang«o«fs.EnumerateSpecificRows. 

tabieTarget: s«i«ction.Targat; 

tableRowsTarget: s«t«<tion.Target; 

TableFrom Value: proc[v: s«i«ction. Value] 
RETURNS [insuncao«fs.lnstance]; 

TablaRowsFromValue: proc[v: Saiaction. Value] 

RETURNS [tr: Tabl«lnt«rchang«0«fs.TableROWS]; 

tabieTarget, tableRowsTarget, TabieFrom Value and TablaRowsFromValue are not 

currently implemented. 
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72.3 Index of Interface Items 

Item Page 

TabieFromSeiection : proc returns 1 

TableFromValue: proc 1 

TablaRowsFromSeiection: proc 1 

TableRowsFromVaiue: proc 1 

tableRowsTarget: Selection 1 

tableTarget: selection 1 
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System TIP Tables 



A.l Overview 

The TIP tables ViewPoint uses are listed on the following pages to provide the programmer 
with a list of the productions available in the general-purpose tables. The Normal tables 
described in §A.2.1 are placed in the TIPStar watershed at boot time and are therefore 
available for use by application programs. (See the TIPStar interface for further 
information about the TIPStar watershed.) Clients are encouraged to use the productions 
in the Normal tables whenever possible rather than generating new tables. Examples of 
use are provided in §A.3. 

A.2 Tables 

A.2.1 Normal Tables 

The set of Normal tables (NormaiMouse.TIP, NormalSoftKeys.TIP, NormalKeyboard.TIP, 
NormalSideKeys.TIP, Normal Backstop.TIP) are registered at startup and pushed into the 
list of TIP tables at the appropriate TIPStar placeholder (mouseActions, softKeys, 
blackKeys, sideKeys, backstopSpecialFocus). (See TIPStar for further explanation about 
placeholders.) The set of Normal tables provides productions for all possible user input. 
Table entries are divided up into logical groups corresponding to the placeholder the table 
will be pushed onto. Thus input actions pertaining to the mouse (Point Down, Adjust 
Down, etc.) appear in the NormaiMouse.TIP table and NormaiMouse.TIP is pushed onto 
the mouseActions placeholder. Key actions from the side function key group that are 
directed at the input focus (MOVE Down, COPY Down, etc.) appear in the 
NormalSideKeys.TIP table and are pushed onto the sideKeys placeholder. Key actions such 
as the alphanumeric keys (A Down, 3 Down, etc.) appear in the NormalKeyboard.TIP table 
and are pushed onto the blackKeys placeholder. Key actions pertaining to the row of 
function keys at the top of the keyboard (CENTER Down, bold Down, etc.) appear in the 
NormalSoftKeys.TIP table and are pushed onto the softKeys placeholder. Key actions from 
the side function key group that are not directed at the input focus (KEYBOARD Down, HELP 
Down) appear in the NormalBackstop.TIP table and are pushed onto the 
backstopSpecialFocus placeholder. 

At the end of ViewPoint boot sequence, the list of TiP.Tables in ViewPoint will appear as in 
Figure A-l. 
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Figure A. 1 TIP Tables after boot 
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-File: Normal Backstop.TIP last edit: 4-Mar'86 18:35:29 

[DEF,if Shift,(SELECT ENABLE FROM 
LeftShift Down « > '1 ; 
RightShift Down a > '1; 

Key47 Down « > "1 ; - JLevellV keyboard LeftShiftAlt 
A12 Down a > "1 ; - JLevellV keyboard RightShiftAlt 

ENDCASE « > '2)1 
SELECT TRIGGER PROM 

FONT Down WHILE Ievel4 »> [lfShift,ShiftFontDown,FontDownl; 
FONT Up WHILE Ievel4 «> [lfShift,ShiftFontUp,FontUp]; 
KEYBOARD Down s> [lfShift,ShiftKeyboardDown,KeyboardDown]; 
KEYBOARD Up « > [lfShift,ShjftKeyboardUp,KeyboardUpl; 
HELP Down WHILE Ievei4 >> [lfShift,ShtftHelpOown,HeipDown]; 
HELP up WHILE ieveiA => [lfShift,ShiftHelpUp.HelpUp]; 
STOP Down « > [lfShift,ShiftStop,Stop]; 
STOP Up - > [ifShift,ShiftStopUp,StopUp]; 

ENDCASE... 
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"File: Normal Key board.TIP last edit: A-Mar-Se 18:38:49 

(OEFjf Shift,(SELEa ENABLE FROM 
LeftShiftOown a > — 1 ; 
RightShiftOown a > --I ; 
K«y47 Down * > SELECT ENABLE FROM 

jLeveU s > "1; - JLevellV keyboard 
jLevelS »>'^: - JLeveiV keyboard 
Ai2Down*>-1; "JLevellV keyboard 

ENDCASE«i>~2)] 
SELEa TRIGGER FROM 

BS Down a > [ifShift, BackWord, Backspace); 
Return Down a > [IfShift, NewLine. NewParagraph); 

Bullet Down « > BUFFEREDCHAR; -level V (non-existent on levellV keyboard) 
singieQuote Down » > BUFFEREDCHAR; -levelV (non-existent on leveilV keyboard) 

- use predicates to distinguish physical keyboards 
Key47Down a > SELECT ENABLE FROM -LeftShiftAlt in levelV terminology 
eLevel4 = > bufferedchar; -European keyboard uses this as char key 
eLevelS a > bufferedchar; -Japanese keyboard uses this as shift key 
enocase a > LeftShiftAltDown; -The key is non-existent on Amer keyboard 

Zero Down a > BUFFEREDCHAR; 
One Down a > BUFFEREDCHAR: 
Two Down a > BUFFEREDCHAR; 
Three Down = > BUFFEREDCHAR; 
Four Down a > BUFFEREDCHAR; 
Five Down a > BUFFEREDCHAR; 
Six Down a > BUFFEREDCHAR; 
Seven Down a > BUFFEREDCHAR; 
Eight Down a > BUFFEREDCHAR; 
Nine Down a > BUFFEREDCHAR; 

A Down a > BUFFEREDCHAR; 
B Down a > BUFFEREDCHAR: 
COown a > BUFFEREDCHAR: 
D Down a > BUFFEREDCHAR; 
E Down a > BUFFEREDCHAR; 
F Down a > BUFFEREDCHAR: 
G Down a > BUFFEREDCHAR; 
H Down a > BUFFEREDCHAR; 
I Down a > BUFFEREDCHAR: 
J Down a > BUFFEREDCHAR; 
K Down a > BUFFEREDCHAR; 
L Down a > BUFFEREDCHAR: 
M Down a > BUFFEREDCHAR; 
N Down a > BUFFEREDCHAR; 
O Down a > BUFFEREDCHAR; 
PDown a > BUFFEREDCHAR: 
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Q Down a > BUFFEREDCHAR; 
R Down 3 > BUFFEREDCHAR; 
S Down s > BUFFEREDCHAR; 
T Down * > BUFFEREDCHAR; 
U Down -a > BUFFEREDCHAR: 

V Down - > BUFFEREDCHAR; 
W Down » > BUFFEREDCHAR; 
X Down ■ > BUFFEREDCHAR; 

Y Down s > BUFFEREDCHAR; 
Z Down > > BUFFEREDCHAR; 

CloseQuote Down a > BUFFEREDCHAR; 

DoubleQuote Down s > BUFFEREDCHAR; -levelV (A10 was unused on leveilV) 

Comma Down * > BUFFEREDCHAR; 

Minus Down a > BUFFEREDCHAR; 

Equal Down 3 > BUFFEREDCHAR; 

LeftBracket Down = > BUFFEREDCHAR: 

Period Down » > BUFFEREDCHAR; 

OpenQuote Down a > BUFFEREDCHAR; 

RightBraclcet Down =« > BUFFEREDCHAR; 

Semicolon Down » > BUFFEREDCHAR; 

Space Down » > BUFFEREDCHAR; 

Slash Down » > BUFFEREDCHAR; 

- use predicates to distinguish physical keyboards 

PARATAB Down 3 > SELECT ENABLE FROM 

eLevelA [If Shift, TabDown. ParaTabOown]; 
levels 3 > [IfShift, TabDown, ParaTabOown]; 
ENOCASE 3> ParaTabOown; 

TAB Down = > SELECT ENABLE FROM 

eLevel4 » > bufferedchar; 

levels 3 > BUFFEREDCHAR; 

ENDCASE a>TabOown; 

LOCK Down = > LOCkOown; 
LOCKUP 3> Lockup; 

JStar keyboards 

» Note: A8, A9, A1 1, A12 and Key47 exist only on the J keyboards. 

All Down a > BUFFEREDCHAR; 
A8 Down M > BUFFEREDCHAR; 
A9Down a > BUFFEREDCHAR; 

- Diagnostics bits 

DiagnosticBitOne Down * > DiagnosticBitOneDown; -levelV (D1 was unused on levellV) 
DiagnosticBitTwo Down 3 > OiagnosticBitTwoOown; -levelV (D2 was unused on tevellV) 

ENDCASE.. 
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-f/7e: NormalMouse.TIP last edit: 3- Apr-86 15:29:19 
OPTIONS Small; 

[OEF,SHIFT,(LeftShift Down | RightShift Down | Key47 Down | A12 Down)] 
[DEFXhOrdP,(SELECT TRIGGER FROM 

'1 Down BEFORE 200 ■ > {time coords Menu PointOown AdjustDbwn}; 

ENOCASE ■ > *2 )] 
[DEF,ChOrdA,(SELECT TRIGGER FROM 

~1 Down BEFORE 200 ■ > {time COORDS Menu AdjustOown PointDown}; 

ENOCASE ■ > ~2 )] 
SELECT TRIGGER FROM 

MOUSE 3 > SELECT ENABLE FROM 

PointDown a > COORDS, PointMotion; 

Adjust Down a > COORDS, AdjuStMOtion; 

MouseMiddle Down a > COORDS, MouseMiddleMotion; 
ENOCASE: 

PointOown ■ > [ChordP,Adjust, 
SELECT ENABLE FROM 

[shift] ■ > {time COORDS Menu PointDown}; 
ENOCASE » > {time COORDS PointDown}]; 
Point up ■ >. 
SELECT ENABLE FROM 

[shift] m > TIME. COORDS, Shift, PointUp; 

ENDCASE M > TIME. COORDS, PointUp; 

Adjust Down ■ > [chord A, Point, 
SELECT ENABLE FROM 

[shift] ■ > {TIME COORDS Menu AdjustDown}; 
ENDCASE ■ > {time COORDS AdjustDown}]; 

Adjust Up ■ > 
SELECT ENABLE FROM 

[shift] m > TIME. COORDS, Shift, AdjustUp; 

ENDCASE a > TIME, COORDS, AdjuStUp; 

MouseMiddle Down a > SELECT ENABLE FROM 
[SHIFT] » > TIME, COORDS, Shift. MouseMiddieDown; 

ENDCASE'x > TIME, COORDS, MOUSCMiddieDown; 
MouseMiddle Up » > SELECT ENABLE FROM 

[SHIFT] > > TIME. COORDS, Shift, MouseMiddleUp; 
ENOCASE a > TIME. COORDS, MouseMiddleUp: 

ENTER a > Enter: 

EXIT a > Exit; . 



ENDCASE.. 
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-f/7e: NormalSideKeys.TIP last edit: 4- Mar-SS 18:34:43 

[OEF,lfShilt,(SELEa ENABLE FROM 
LeftShift Down »>'^; 
RightShift Down s> ~1; 

Key47 Down « > ' 1 ; JLevellV keyboard LeftShiftAlt 
A12 Down at > "1 ; - JLevellV keyboard RightShiftAlt 
ENOCASE » > "2)1 



SELECT TRIGGER FROM 

- left function keys on both daybreak and dlion keyboards 
AGAIN Down »> [lfShift,ShiftAgainDown,AgainOown]; 
AGAIN Up a> [lfShift,ShiftAgainUp,AgainUp]; 

DELETE Down »> [lfShift,ShiftOeleteDown,DeleteOown]; 

DELETE Up a > [ifShift^ShiftOeieteUp.OeieteUp]; 

FIND Down m> [lfShift,ShtftFindDown,FindDown]; 

FIND up »> [lfShift,ShiftFindUp,FindUp]; 

COPY Down s > [tfShift,ShiftCopyOown,CopyOown]; 

COPY up «> [lfShift,ShiftCopyUp,CopyUp]; 

SAME Down 3 > [lfShift,ShiftSameOown,SameOown]; 

SAME Up a > [lfShift,ShiftSameUp,SameUp]; 

MOVE Down 3 > [lfShift,ShiftMoveOown,MoveOown]; 

MOVE Up >> [lfShift,ShiftMoveUp,MoveUp]; 

OPEN Down a > [lfShift,ShiftOpenOown,OpenDown]; 

OPENUp a> [ifShift,ShiftOpenUp,OpenUp]; 

PROPS Down M> [lfShift,ShiftPropsDown,PropsDown]; 

PROPSUp [lfShift,ShiftPropsUp,PropsUp]; 

- part of left function group on daybreak and right function group on dlion 
UNDO Down >> [lfShift,ShiftUndoOown,UndoOown]; 
UNDO Up ■ > [ifShift,ShlftUndoUp,UndoUp]; 

beside space bar on daybreak and in right function group on dlion 
EXPAND Down ai > [IfShift.Oef IneDown^ExpandDown]; 
EXPAND Up « > [lfShift,OefineUp,ExpandUp]; 

- right function keys on both keyboards 

NEXT Down a > [lfShift,SkipOown,NextDown]; 
NEXTUp « > [lfShift,SkipUp.NextUp]; 

- part of the right function group on dlion but moved to softkeys on daybreak 
MARGINS Down WHILE Ievel4 a > IlfShift,ShiftMarginsOown,MarginsOown]; 
MARGINS Up WHILE Ievel4 ■> [lfShift.ShiftMarginsUp,MarginsUp]; 

- calculator key pad on daybreak 

~ (has no meaning on dlion except in virtual keypad) 
K«ypadZeroDown > > BUFFEREDCHAR; 
KeypadOne Down * > BUFFEREDCHAR; 
KeypadTwo Down ■ > BUFFEREDCHAR; 
KeypadThree Down * > BUFFEREDCHAR; 
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KeypadFour Down > > BUFFEREDCHAR; 
KeypadFive Down ■ > BUFFEREDCHAR; 
KeypadSix Down a > BUFFEREDCHAR; 
KeypadSeven Down ■ > BUFFEREDCHAR; 
KeypadEight Down a > BUFFEREDCHAR; 
KeypadNine Down a > BUFFEREDCHAR; 
KeypadAddOown a > BUFFEREDCHAR; 
KeypadSubtract Down a > BUFFEREDCHAR; 
KeypadMultiply Down a > BUFFEREDCHAR; 
KeypadOivide Down a > BUFFEREDCHAR; 
KeypadPeriod Down a > BUFFEREDCHAR; 
KeypadComma Down a > BUFFEREDCHAR; 

KeypadClear Down a > [lfShift,ShiftClearDown,ClearDown]; 
KeypadCiearUp a > [lfShift,ShiftClearUp,C]earUp]; 

ENDCASE... 
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- fi/e; NormalSoftKeys.TIP last edit: S-Mar-SS 12:40:42 
" SoftKeys are the toprow of function Iceys 

[DEF,lfShift,(SELECT ENABLE FROM 
LeftShift Down » > '1 ; 
RightShift Down ■ > '1 ; 

Key47 Down « > '1 ; - JLevellV Iteyboard LeftShiftAlt 
A12 Down a > '1 ; - JLeveilV Ifeyboard RigtitShiftAlt 
ENOCASE a > '2)] 



SELECT TRIGGER FROM 

~ top function l(eys 

CENTER Down »> [IfShift.ShiftCenterOownXenterDown]; 
CENTER up *> [lfShift,ShiftCenterUp,CenterUpl; 
BOLD Down « > [IfShift.UnboldDown.BoidOown]; 
BOLD Up a > [lfShift,UnboldUp,BoiclUp]; 
iTALicsoown a > [IfShifttShiftltalicsOown.itaiicsOownl.- 
iTALicsup - > [lfShift,ShiftltaiicsUp,ltaiicsUp]; 

Case key on daybreak only 
Cas«Down * > [lfShift,SHiftCaseOown,CaseOown]; 
Case up « > [lfShift,ShiftCaseUp,CaseUp]; 

UNDERLINE Down ■ > SELECT ENABLE FROM 

Ievel4 ■ > [IfShift.ShiftUnderlineDown.UnderlineDown]; 

levels a > [lfShift,ShiftObkUnderlineOown,ObkUnderlineOown]; 

ENDCASE a > [IfShift.ShiftUnderllneOown.UnderllneOown]; 

UNOERLINE Up a > SELECT ENABLE FROM 

Ievel4 a > [IfShift.ShiftUnderlineUp.UnderlineUpl; 

levels a > [lfShift,ShlftObkUnderlineUp,ObkUnderlineUp]; 

ENDCASE a > [lfShift,ShiftUnderllneUp,UnderlineUp]; 

-strikeout and supersub on daybreak only 
Strikeout Down a > [lfShift,ShlftStrlkeoutOown,StrikeoutDown]; 
strikeout Up a > [lfShift.ShiftStrikeoutUp,StrikeoutUp]; 
SuperSuboown a > [lfShlft,ShiftSuperSubOown,SuperSubOown]; 
SuperSubup a > [lfShift,ShiftSuperSubUp,SuperSubUp]; 

-superscript and subscript on dlion only 

SUPERSCRIPT Down a > [lfShift,ShiftSuperscriptOown,SuperscriptOown]; 
SUPERSCRIPT up a > [IfShift.ShlftSuperscriptUp.SuperscrlptUp]; 
SUBSCRIPT Down a > [lfShift,ShiftSubscriptDown,SubscriptDown]; 
suBSCRiPTUp a > [lfShift,ShiftSubscriptUp.SubscriptUp]; 

SMALLER Down a > SELECT ENABLE FROM 

Ievel4 a > [lfShift,LargerDown,SmallerDown]; 

levels a > [lfShift,DbkLargerOown,ObkSmallerDown]; 

ENDCASE a > [lfShift,LargerDown,SmallerOown]; 

SMALLER up a > SELECT ENABLE FROM 

levelA a > [lfShift,LargerUp,SmallerUp]; 

levels a > [lfShift,DbkLargerUp,DbkSmallerUp]: 
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ENDCASE ■ > [IfShift^LargerUp.SmallerUpI; 

-margins key is a softkey on daybreak and a right function key on diion 
MARGINS Down WHILE levels ■> [lfShift,ShiftMarginsOown,MarginsDownl; 
MARGINS Up WHILE levels m > [IfShift.ShiftMarginsUp.MarginsUp]; 

-defaults key on dlion only 

DEFAULTS Down ■ > [IfShift.ShiftOefaultsOown.OefauitsOown]; 
DEFAULTS Up ■ > [lfShift,ShiftOefaultsUp,OefaultsUp]; 

-font key is a softkey on daybreak and a right function key on dlion 
FONTOown WHILE levels ■ > [lfShift,ShiftFontDown,FontDown]; 
FONT Up WHILE levels ■ > [lfShift,ShiftFontUp,FontUp]; 



ENDCASE... 
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A.2.2 Mouse Mode Tables 

The mouse mode tables refer to the set of tables that will be swapped in and out of the 
nPStar watershed at the mouseActions placeholder, depending on the mode set by 
TiPStar.SetMode. Note: mode = normal will return NormalMouse.TIP to the watershed. 

-fiYe: CopyModeMouse.TIP last edit: 28-May-85 18:12:42 

OPTIONS Small: 

SELECT TRIGGER FROM 

MOUSE * > SELEa ENABLE FROM 

Point Down a > COORDS. CopyModeMotion, KEY; 

Adjust Down s > COORDS. CopyModeMOtlon, KEY; 
ENOCASE; 

Point Down « > COORDS, CopyModeOown, KEY; 
Point Up 3 > COORDS, CopyModeUp, KEY; 
Adjust Down » > COORDS. CopyModeDown, KEY; 
Adjust Up > > COORDS. CopyModeUp, key; 

ENTER a > CopyModeEnter; 
EXIT * > CopyModeExit; 

ENOCASE.. 



All 
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-File: MoveModeMouse-TIP last edit: IS-May-SS 16:37:23 jl^ 

OPTIONS Small; 

SELECT TRIGGER FROM 

MOUSE a > SELECT ENABLE FROM 
Point Down a > COORDS, MoveModeMotion, KEY; 

Adjust Down 3 > COORDS, MoveModeMotion, key; 

ENOCASE: 

Point Down « > COORDS, MoveModeDown, KEY: 
Point Up a > COORDS. MOVeModellp, KEY; 
Adjust Down » > COORDS, MoveModeOOwn, KEY; 

Adjust Up a > COORDS. MovelVlodeUp, key; 

ENTER » > MoveModeEnter; 
EXIT « > MoveModeExit: 

ENDCASE.. 
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-fiVe: SameAsModeMouse.TIP /ast ed/t: 28-May-8S 18:13:22 
OPTIONS Small; 
SELECT TRIGGER FROM 
MOUSE a > SELECT ENABLE FROM 

Point Down » > COORDS. SameAsModeMotion, key,- 
Adjust Down » > COORDS, SameAsModeMoti'on, key; 

ENDCASE: 

Point Down * > COORDS, SameAsModeDown, key; 
Point up 3 > COORDS, SameAsModeUp, key; 
Adjust Down « > COORDS, SameAsModeDown, key; 
Adjust Up s > COORDS, SameAsModeUp, key; 

enter a > SameAsModeEnter; 
EXIT M > SameAsModeExit; 



ENDCASE... 
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A.3 Usage/Examples 



A.3.1 Using NormalSoftKeys.TIP when installing client softKeys 
" define the Atoms for my Notif yProc to use — 

centerDown, boldOown, italicsOown, underlineOown, superscriptOown, 
subscriptOown, smallerDown, defauitsOown : Atom.ATOM *- Atom.nuil; 

Init: PROCEDURE s 
BEGIN 

~ initialize my Atoms — 
centerOown <- Atom.MakeAtom("CenterOown"]; 
boldDown «>Atoin.MakeAtom["BoldOown"L]: 
itaiicsOown 4-Atom.MakeAtom{"ltalicsOown "l]; 
underlineOown <- Atom.MakeAtom[''UnderiineOown''L]; 
superscriptDown <- Atom.MakeAtom("SuperscriptDown"L]; 
subscriptOown <-Atoni.MakeAtom['*SubscriptOown"L]: 
smailerOown <-Atom.MakeAtom(''SmallerOown''L]: 
END; "Init 



— somewhere in the code — 
softKey Handle «-SoftKeys.Push( 
notifyProc: MyNotif yProc. 

labels: DESCRiPTOR(labels, SoftKeys.numberOf Keys] ]: 
MyNotif yProc: TiP.NotifyProc = 

BEGIN 

FOR input: TiP.Results *- results, Input.next until input s nil oo 
WITH z: input select from 
atom » > select z.a from 
centerOown => -Do something interesting--; 
boldOown »> —Do something interesting—; 
italicsOown = > —Do something interesting—; 
underlineOown => —Do something interesting— ; 
superscriptDown = > —Do something interesting—; 
subscriptOown = > —Do something interesting—; 
smallerOown a > —Do something interesting—; 
defauitsOown »> —Do something interesting— ; 

ENOCASE 
ENDCASE 
ENDLOOP 

END; — MyNotifyProc 

MyNotifyProc will be attached to NormalSoftKeys.TIP by the SoftKeys implementation. 
Until this client does a SoftKeys.Remove, whenever the user presses one of the top row 
function keys MyNotifyProc will be called with the appropriate production from the 
NormalSoftKeys.TIP. 
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A.3.2 Attaching a Notify Proc to One of the Normal Tables 

If a client application wants to grab the use, for example, of all the side keys for some 
period of time, it can attach a notifyProc to the NormaiSideKey$.TlP table by calling: 

old <-TiP.SetNotifyProcForTable(TiPStar.GetTabie(sideKeys], My NotifyProc]: 
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A.4 Index of TIP Tables 



Item Page 

CopyModeMouse.TIP 1 1 

MoveModeMouse.TIP 12 

NormaiBackstop.TlP 3 

NormaiKeyboard.TIP 4 

NormalMouse.TtP 6 

NormaiSideKeys.TIP 7 

NormalSoftKeys.TIP 9 

SameAsModeMouse.TIP 13 
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References 



The following documents should be studied before or in conjunction with this manual: 

• Mesa Language Manual (610E00170). 

• XDE User Guide f610E00140). 

• Pilot Programmers Manual ( 610E00X60). 

• Srvices Programmer's Guide: Filing Programmer's Manual (61 OEOO 1 80). 

In addition, any other documentation accompanying a release of ViewPoint should be 
consulted before writing any programs. A list of this documentation can be found in the 
release message for each release. 
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Listing of Atoms 



C.l Overview 



Atoms (see the Atom interface) are used in several places in ViewPoint. This appendix 
contains a list of the strings that represent them. 



C.2 Atoms as TIP Results in the System TIP Tables 

Most of the right-hand sides (TIP results) of the productions in the system-provided TIP 
Tables (see Appendix A) contain atoms. 

AdjustDown 

AdjustMotion 

AdjustUp 

AgainDown 

AgainUp 

aLeveI4 

aLevei5 

Backspace 

BackWord 

BoldDown 

BoldUp 

CaseDown 

CaseUp 

CenterDown 

CenterUp 

Clear Down 

ClearUp 

Copy Down 

CopyModeDown 

CopyModeEnter 

CopyModeExit 

CopyModeMotion 

CopyModeMouse 

CopyModeUp 

CopylJp 

Dbk Larger Down 
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DbkLargerUp 

DbkSmallerDown 

DbkSmallerUp 

DbkUnderlineDown 

DbkUnderlineUp 

Defaults Down 

DefaultsUp 

DefineDown 

DefineUp 

Delete Down 

Delete Up 

DiagnosticB itOne 

DiagnosticB i tOne Down 

DiagnosticBitTwo 

DiagnosticBitTwoDown 

eLevel4 

eLevelS 

Enter 

Exit 

Expand Down 

ExpandUp 

FindDown 

FindUp 

FontDown 

FontUp 

HelpDown 

HelpUp 

Italics Down 

ItalicsLTp 

jLevel4 

jLevelS 

KeyboardDown 

Keyboard Up 

KeypadAdd 

KeypadClear 

KeypadComma 

KeypadDivide 

KeypadEight 

KeypadFive 

KeypadFour 

KeypadMultiply 

KeypadNine 

KeypadOne 

KeypadPeriod 

KeypadSeven 

KeypadSix 

KeypadSubtract 

KeypadThree 

KeypadTwo 

KeypadZero 

Larger Down 

Larger Up 
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LeftShiftAltDown 

leveI4 

levels 

LockDown 

Lockup 

MarginsDown 

Margins Up 

MouseMiddleDown 

MouseMiddle Motion 

MouseMiddieUp 

MoveDown 

MoveModeDown 

MoveModeEnter 

MoveModeExit 

MoveModeMotion 

MoveModeMouse 

MoveModeUp- 

NewLine 

NewParagraph 

NextDown 

NextUp 

OpenDown 

OpenQuote 

OpenUp 

ParaTabDown 

PointDown 

PointMotion 

PointUp 

Props Down 

Props Up 

Same AsMode Down 

Same AsMode Enter 

SameAsModeExit 

SameAsModeMotion 

SameAsModeMouse 

SameAsModeUp 

SameDown 

Same Up 

Shift Again Down 

ShiftAgainUp 

ShiftCaseDown 

ShiftCaseUp 

ShiftCenterDown 

ShiftCenterUp 

ShiftClearDown 

ShiftClearUp 

ShiftCopyDown 

ShiftCopyUp 

ShiftDbkUnderlineDown 

ShiftDbkUnderlineUp 

ShiftDefaultsDown 

ShiRDefaultsUp 
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Shift Delete Down 

ShiftDeleteUp 

ShiftFindDown 

ShiftFindUp 

ShiftFontDown 

ShiftFontLTp 

ShiftHelpDown 

ShiftHelpUp 

ShiftltalicsDown 

ShiftltalicsL'p 

ShiftKey board Down 

ShiftKey board U p 

ShiftMargi ns Do wn 

ShiftMarginsL'p 

ShiftMoveDown 

ShiftMoveUp 

ShiftOpenDown 

ShiftOpenUp 

ShiftPropsDown 

ShiftPropsUp 

ShiftSame Down 

ShiftSameUp 

ShiftStop 

ShiftStopUp 

ShiftStrikeoutDown 

ShiftStrikeoutUp 

ShiftSubscriptDown 

ShiftSubscriptUp 

ShiftSuperscriptDown 

ShiftSuperscriptL'p 

ShiftSuperSubDown 

ShiftSuperSubUp 

ShiftL'nderlineDown 

ShiftUnderlineUp 

ShiftUndoDown 

ShiftUndoUp 

SkipDown 

SkipUp 

SmallerDown 

SmallerUp 

Stop 

StopUp 

Strikeout 

StrikeoutDown 

StrikeoutUp 

subscript 

SubscriptDown 

SubscriptUp 

Superscript Down 

SuperscriptUp 

SuperSubDown 

SuperSubUp 
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Tab Down 

UnboIdDown 

UnboldUp 

UnderlineDown 

UnderlineUp 

Undo Down 

UndoUp 

C.3 Passed as the **Atoin*' Parameter to a Containee.GenericProc 

These atoms may be passed to a Containee.GenericProc us the atom parameter, indicating 
what operation the GenericProc should perform: 

CanYouTakeSelection 

FreeMenu 

Menu 

Open 

Props 

TakeSelection 
TakeSe lectionCopy 

C.4 Event Atoms 

Events are identified by atoms (see the Event interface). The following events are 
explained in further detail in the chapter indicated. 

Event Chapter where discussed 

ApplicationLoaded ApplicationFolder 

AttemptingLogoff StarDesktop 

BlackKeysChange BlackKeys 

DesktopWindowAvailable StarDesktop 

Newlcon StarDesktop 

Logoff StarDesktop 

Logon StarDesktop 

C.5 Atomic Profile Atoms 

AtomicProfile is used to save various values globally. Values are saved with the following 
atoms. 

FullUserName-Fuliy qualified user's name as entered by the user at logon. 



C.6 Other 



The Atom interface allows any value to be associated with any pair of atoms (see 
Atom.GetProp, Atom.Pair, etc.). 
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Atom Property atom 

CurrentUser Identity Handle 

CurrentUser Simpleldentitytiandie 



Value 

identity.Handle for the currently logged 
on user. This is created at logon if the 
user enters a password; it can be used to 
access any Network Service. It is 
created with strong authentication. 

Just like IdentityHandle above, but 
created with simple authentication. 
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This appendix lists all public items from the public interfaces, i.e., the files in 
XStringPubiicdf and BWSPublicdf . 

-- ApplicationFolder Atom AtomicProfile Attention BlackKeys BWSAttributeTypes 
BWSFileTypes BWSZone Catalog Containee ContainerCache ContainerCacheExtra 
ContainerSource ContainerWindow ContainerWindowExtra ContainerWindowExtra2 
Context Cursor Display Event FileContainerShell FileContainerSource 
FileContainerSourceExtra FileContainerSource Extra 2 FormWindow 
FormWindowMessageParse IdleControl KeyboardKey KeyboardWindow LevellVKeys 
MenuData MessageWindow OptionFile PopupMenu ProductFactoring 
ProductFactoringProducts ProductFactoringProductsExtras PropertySheet Prototype 
PrototypeExtra Selection SimpleTextDisplay SimpleTextEdit SimpleTextFont 
SimpleTextFontExtra SoftKeys StarDesktop StarWindowShell StarWindowShellExtra 
StarWindowShellExtra2 TIP TIPStar TIPX Undo UnitConversion Window XChar XCharSetO 
XCharSet164 XCharSet356 XCharSet357 XCharSet360 XCharSet361 XCharSet41 
XCharSet42 XCharSet43 XCharSet44 XCharSet45 XCharSet46 XCharSet47 XCharSets 
XComSoftMessage XFormat XLReal XMessage XString XTime XToken 

Abs: -XLReal" procedure (Number] returns [Number]; 
accentedLatin: -XC/»arSetJ67-XCharSets.Sets = LOOPHOLE[241]; 
accuracy: -Xt/?ea/-- natural = 13; 

Acquire: -Context- procedure [type: Type, window: Window. Handle] 
returns [Data]; 

Action: -ContainerSource- Typ£ = {destroy, relist, sleep, walceup}; 
Action :---Se/ect/on-- TYPE = machine depenoent{ 

clear, mark, unmark, delete, clearlfHaslnsert, save, restore, firstFree, 

last(255)}; 

actionToWindow: -TIP- packed array KeyName of boolean; 
ActOn: -ContainerSource- ActOnProc; 
ActOn: -Selection- procedure [action: Action]; 
ActOnProc: -ContainerSource- type = procedure [ 

source: Handle, action: Action]; 
ActOnProc: -Se/ect/on-- type = procedure [data: ManagerData, attion: 
Action] 

returns [cleared: boolean 'false]; 
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Add: -PrototypeExtra- procedure ( 

file: NSFiie.Handle, version: Prototype.Version, 

subtype: Prototype.Subtype '0, session: NSFile.Session 'LOOPHOLE[0]]; 
Add: -XLReal- procedure [a: Number, b: Number] returns [Number]; 
AddClientOef inedCharacter: SimpleTextFont- procedure [ 

width: cardinal, height: cardinal, bitsPerUne: cardinal, bits: long pointer, 

offsetlntoBits: cardinal *0] returns (XString.Character]; 
Add Data: -ContainerCache-- type = record ( 

ciientData: long pointer, 

clientDataCount: cardinal, 

clientStrings: long descriptor for array cardinal of XString.ReaderBody]; 
AddDependencies: -Event- procedure [ 

agent: AgentProcedure. myData: long pointer, 

events: long descriptor for array cardinal of EventType, 

remove: FreeDataProcedure "nil] returns (dependency: Dependency]; 
AddDependency: -rf vent- procedure [ 
. agent: AgentProcedure, myData: long pointer, event: EventType, 

remove: FreeDataProcedure 'nil] returns [dependency: Dependency]; 
Addltem: --MenuData- procedure [menu; Menu Handle, new: ItemHandle]; 
AddMenultem: -Attention- procedure [item: MenuData.ltemHandle]; 
AddPopupMenu: -StarWindowShell- procedure [ 

sws: Handle, menu: MenuData.MenuHandle]; 
AddReferenceToOesktop: -StarDesktop- procedure [ 

reference: NSFile.Reference, place: Window.Place "nextPlace]; 
AddToSystemKeyboards: -KeyboardKey- procedure [keyboard: 
BtackKeys. Keyboard]; 

AdjustProc: -StarW/ndowSAie//- type = procedure [ 

sws: Handle, box: WIndow.Box, when: When]; 
AgentProcedure: -Event- type = procedure [ 

event: EventType, eventData: long pointer, myData: long pointer] 

RETURNS [remove: boolean 'false, veto: boolean "false]; 
AllocateAndlnsert: -MessageWindow- procedure [ 

parent: Window.Handle, place: Window.Place *LOOPHOLE[0], 

dims: Window.Dims "LOOPHOLE[23417B], zone: uncounted zone 'LOOPHOLEiO], 

lines: cardinal * 10] returns [Window.Handle]; 
AllocateCache: -ContainerCache- procedure returns [Handle]; 
AliocateMessages: -XMessage- procedure [ 

applicationName: long string, maxMessages: cardinal, ciientData: CiientData, 

proc: DestroyMsgsProc] returns [h: Handle]; 
Alphabetic: -XToken- FilterProcType; 
AlphaNumeric: -XToken- FilterProcType; 
Append: -XTime- procedure ( 

w: XString.Writer, time: System. GreenwichMeanTime "defaultTime, 

template: XString. Reader 'dateAndTime, Itp: LTP 'useSystem]; 
AppendChar: -XString- procedure [ 

to: Writer, c: Character, extra: cardinal '0]; 
AppendExtensionif Needed: -XStr/ng- procedure [to: Writer, extension: Reader] 

RETURNS [didAppend: boolean]; 
Appendltem: -ContainerCache- procedure [cache: Handle, addData: AddData] 

. RETURNS [handle: ItemHandle]; 
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Appendltem: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, line: Line, preMargin: cardinal 0, 

tabStop: cardinal 'nextTabStop, repaint: boolean "true]; 
AppendLine: -Forml/l^/ndow- procedure [ 

window: Window. Handle, spaceAboveLine: cardinal '0] returns [line: Line]; 
AppendReader: -XString- procedure [ 

to: Writer, from: Reader, fromEndContext: Context 'unknownContext, 

extra: cardinal *0]; 
AppendStream: -XString- procedure [ 

to: Writer, from: Stream.Handle, nfiytes: cardinal, 

fromContext: Context "vanillaContext, extra: cardinal *0] 

returns [bytesTransf erred: cardinal]; 
AppendSTRING: -XString- procedure [ 

to: Writer, from: long string, homogeneous: boolean ''false, 

extra: cardinal *0|; 
ArabicFirstRightToLeftCharCode: -XChar- Environment. Byte = 48; 
Arc: '-Display- procedure [ 

window: Handle, place: Window.Place, radius: integer, startSector: cardinal, 

stopSector: cardinal, start: Window.Place, stop: Window.Place, 

iineStyle: LineStyle "nil, bounds: Window.BoxHandle 'nil]; 
ArcCos: -XiReai- procedure [x: Number] returns [radians: Number]; 
ArcSin: -XLReal- procedure [x: Number] returns [radians: Number]; 
ArcTan: -XLReal— procedure [x: Number] returns [radians: Number]; 
ArrayHandle: -MenuData- type a long descriptor for array cardinal of 

ItemHandie; 

ArrowFlavor: -StarWindowSheU- TYPB = {pageFwd, pageBwd, forward, backward}; 
ArrowScrollAction: -StarWindowShell- type = {start, go, stop}; 
ArrowScrollProc: -StarWindowShell- type = procedure [ 

sws: Handle, vertical: boolean, flavor: ArrowFlavor, 

arrowScrot I Action: ArrowScrollAction 'go]; 
ATOM : -A torn- type [ 1 ]; 
atom: ~nP- type = Atom.ATOM; 
attemptingLogoff : -StarDesktop-- Atom. atom; 
AttentionProc: -r/P- type = procedure [window: Window.Handlej; 
AttributeFormatProc: -rFileContainerSource-- type s procedure [ 

containeelmpi: Containee.lmplementation, contai nee Data: Containee.DataHandie, 

attr: NSFiie.Attribute, displayString: XString. Writer]; 
BackScanClosure: -XString- type s record [ 

proc: BackScanProc, env: long pointer]; 
BackScanProc: "XStr/ng- TYPE s procedure [ 

beforePos: cardinal, env: long pointer] 

returns [pos: cardinal, context: Context]; 
backStopinputFocus: -r/P- readonly Window.Handle; 
beforeltemZero: -Conta/nerSoorce-- Itemlndex = 177776B; 
beforeLogonSession: -Catalog- NSFile.Session; 
BeginFiil: -Contai nerCache- procedure [ 

cache: Handle, fillProc: FillProc, clients: long pointer, 

fork: boolean 'true]; 
Bit: -LevellVKeys- type = KeyStations.Bit; 
BitAddress: -0/sp/ay- type = BitBltBitAddress; 
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BitAddressFromPlace: -Display- procedure ( 

base: BitAddress, x: natural, y: natural, raster: cardinal] 

RETURNS [BitAddress]; 
BitBltFlags: -0/sp/ay- TYPE = BitBlt.BitBltFlags; 
bitFlags: -Display- BitBltFlags; 
Bitmap: -Display- procedure ( 

window: Handle, box: Window.Box, address: BitAddress, 

bitmapBitWidth: cardinal, flags: BitBltFlags 'paintFlags, 

bounds: Window.BoxHandle ^imil]; 
Bitmap: -FormWindow- type = record [ 

height: cardinal, 

width: CARDINAL, 

bitsPerLine: cardinal, 
bits: EnvironmentBitAddress]; 
BitmapPlace: -Window- procedure [window: Handle, place: Place "LOOPHOLE[0]] 
returns [Place]; 

BitmapPlaceToWindowAndPtace: -Window- procedure [bitmapPlace: Place] 

returns [window: Handle, place: Place]; 
Bits: -XLReal- type = array [0..3] of cardinal; 
Black: -Display- procedure [ 

window: Handle, box: Window.Box, bounds: Window.BoxHandle 'nil]; 
BlackParailelogram: -Display- procedure [ 

window: Handle, p: Parallelogram, dstFunc: OstFunc ^null, 

bounds: Window.BoxHandle 'nil]; 
Blanks: -XFormat- procedure [h: Handle "nil, n: cardinal M]; 
Block: -Xformat- PROCEDURE [h: Handle "nil, block: Environment.Block]; 
Block: -XString- procedure [r: Reader] 

RETURNS [block: Environment.Block, context: Context]; 
BodyEnumProc: -StarWindowShell-Jypz = procedure [victim: Window.Handle] 

RETURNS [stop: BOOLEAN "FALSE); 

Boolean: -XTo/icen- procedure [h: Handle, signalOnError: boolean "true] 

returns [true: boolean); 
BooleanChangeProc: -FormWindow- type = procedure [ 

window: Window.Handle, item: ItemKey, calledBecauseOf: ChangeReason, 

newValue: boolean]; 
BooleanFalseDefault: --Prope/tySA)eet-- type = boolean "false; 
BooleanltemLabel: -Form VV/ndow- TYPE = record ( 

van select type: BooleanttemLabelType from 
string = > [string: XString. ReaderBody], 
bitmap = > [bitmap: Bitmap], 

ENDCASE]; 

BobleanltemLabelType: -FormWindow- "^vpe = {string, bitmap}; 
Box: -KeyboardWindow- type = record [ 

place: Window.Place, width: integer, height: integer]; 
Box: -Window- TYPE = record [place: Place, di-ms: Dims]; 
BoxEnumProc: -Window- type = procedure [Handle, Box); 
BoxesAreDisjoint: -Window- procedure [a: Box, b: Box] returns [boolean]; 
boxFlags: -Display- BitBltFlags; 
BoxHandle: -Window- type = long pointer to Box; 
Brackets: -XToken- QuoteProcType; 

BreakCharOption: -XStr/ng- type - = {ignore, appendloFront, leaveOnRest}; 
BreakTable: -XStr/ng- type = long pointer to BreakTableObject; 
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BreakTableObject: -XString- type a record [ 
otherSets: StopOrNot 'stop, 
set: Environment. Byte "0, 

codes: packed array [0..2551 of StopOrNot 'ALL(not]]; 

Brick: -Display- type = long descriptor for array cardinal of cardinal; 

BufferProc: -SimpleTextDisplay- type » procedure [ 

result: Result, string: XString. Reader, address: EnvironmentBitAddress, 
dims: Window.Dims, bitsPerLine: cardinal] returns [continue: boolean); 

Byte: -XStr/ng- TYPE = Environment. Byte; 

ByteLength: -XString- procedure [r: Reader] returns [cardinal]; 

Bytes: -XString- type = long pointer to ByteSequence; 

ByteSequence: -XString- type s record ( 

PACKED sequence COMPUTED CARDINAL OF Byte]; 

CacheFiilStatus: -ContainerCache- type = { 

no, inProgress, inProgressPendingAbort, inProgressPendingJoin, yes, 

yesWithError, spare}; 
CallBack: -TIP- procedure [ 

window: Window. Handle, table: Table, notify: CallBackNotifyProc]; - 
CallBackNotifyProc: -TIP- type = procedure [ 

window: Window.Handie, results: Results] returns [done: boolean); 
CanceiPeriodicNotify: -TIP- procedure [PeriodicNotify] 

returns [null: PeriodicNotify); 
CanYouConvert: ~Se/ect/on- procedure [ 

target: Target, enumeration: boolean 'false] returns [yes: boolean); 
CanYouTake: -ContainerSource- CanYouTakeProc; 
CanYouTakeProc: -ContainerSource- type = procedure [ 

source: Handle, selection: Setection.ConvertProc 'nil] 

returns [yes: boolean]; 
caretRate: -TIP- Process. Ticks; 

CatalogProc: -Cata/og- type = procedure [catalogType: NSFile.Type) 

RETURNS [continue: boolean 'true); 
Changelnfo: -ContainerSource- type = record [ 

var: select changeType: ChangeType from 
replace = > [item: Item Index), 

insert » > [insertlnfo: long descriptor for array cardinal of Editlnfo), 
delete = > [deletelnfo: Editlnfo], 

ait s > NULL, 

noChanges = > null, 
endcase); 

ChangeProc: -Containee- ^ype = procedure [ 

changeProcData: long pointer, data: DataHandle 'nil, 

changedAttributes: NSFIIe.Seiections '[xxxx], noChanges: boolean 'false); 
ChangeProc: -ContainerSource- type = procedure ( 

ChangeProcData: long pointer, changelnfo: Changelnfo); 
ChangeReason: -Form Window- type = {user, client, restore}; 
ChangeScope: -FileContainerSource- procedure ( 

source: ContainerSource. Handle, newScope: NSFile.Scope); 
ChangeSizeProc: -SimpleTextEdit- type = procedure [ 

f: Field, oldHeight: integer, newHeight: integer, repaint: boolean); 
ChangeType: -ContainerSource- type = { 

replace, insert, delete, all, noChanges}; 
Char: -XFormat- procedure [h: Handle "nil, char: XString. Character); 
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Character: -XChar- type = word; 

Character: -XStr/ng- TYPE = XChar. Character; 

CharacterLength: -XString- procedure [r: Reader] returns [cardinal]; 

CharRep: -XChar- type = machine dependent record [ 

set(0:0..7): Environment.Byte, code(0:8..15): Environment Byte]; 
CharTranslator: -TIP- type = record [proc: KeyToCharProc, data: long pointer]; 
ChoiceChangeProc: -FormW'mdoW" type = procedure [ 

window: Window. Handle, item: ItemKey, cailedBecauseOf: ChangeReason, 

oldValue: Choiceindex, newValue: Choicelndex]; 
ChoiceHintsProc: -FormWindow- type = procedure [ 

window: Window. Handle, item: ItemKey] 

RETURNS [ 

hints: long descriptor for array cardinal of Choicelndex, 

f reeHi nts: FreeChoiceH i ntsProc] ; 
Choicelndex: -FormWindow- type = cardinal [0..37777B]; 
Choi ce Item: -Form W/mdow- TYPE = record [ 
var: select type: ChoiceltemType from 

string = > [choiceNumber: Choicelndex, string: XString. ReaderBody], 

bitmap » > [choiceNumber: Choicelndex, bitmap: Bitmap], 

wraplndicator = > null, 

ENDCASEj; 

Choiceltems: -FormWindow- type = long descriptor for array Choicelndex of 
Choiceltem; 

ChoiceltemType: -FormWindow- jy?^ = {string, bitmap, wraplndicator}; 

Circle: -Display- procedure [ 

window: Handle, place: Window.Place, radius: integer, 
lineStyle: LineStyle "nil, bounds: Window.BoxHandle "nil]; 

Clarity: -W/ndow- TYPE = {isClear, isDirty}; 

Clear: -Attention- procedure; 

Clear: -MessageWindow- procedure [window: Window.Handle]; 
Clear: -Selection- procedure [unmark: boolean "true]; 
ClearlnputFocusOnMatch: -f/P- procedure [Window.Handle]; 
ClearManager: -TIP- procedure; 
ClearOnMatch: -Selection- procedure [ 

pointer: ManagerOata, unmark: boolean "true]; 
ClearSticky: -Attention- procedure; 
ClearWriter: -XString- procedure [w: Writer]; 
clickTlmeout: -f/P- System. Pulses; 
ClientData: -XFormat- type = long pointer; 
ClientData: -XMessage- ^ype = long pointer; 

clientDi rectory Words: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 
10373B; 

clientFileWords: --8WSi4ttr/baterypes- NSFile.ExtendedAttributeType = 10372B; 

Clients: -ContainerCache- procedure [cache: Handle] 
returns [clients: long pointer]; 

dientSize: --flWSAttr/buterypes- NSFile.ExtendedAttributeType = 10375B; 

dientStatus: -SWSAttf/buterypes-- NSFile.ExtendedAttributeType = 10374B; 

Code: -XChar- procedure [c: Character] returns [code: Environment.Byte]; 

CodesO: -XCharSetO- type = machine dependent{ 

null, tab(9), lineFeed, formFeed(12), newLine, esc(27), space(32), 
exclamationPoi nt, neutral DoubleQuote, numberSign, currency, percentSign, 
ampersand, apostrophe, openParenthesis, closeParenthesis, asterisk, plus, 
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comma, minus, period, slash, digitO, digiti , digit2, digits, digit4, digits, 
digit6, digit?, digits, digits, colon, semicolon, lessThan, equals, 
greaterThan, questionMark, commercialAt, upperA, upperB, upperC, upperO, 
upperE, upperF, upperG, upperH, upperl, upperj, upperK, upperL, upperM, 
upperN, upperO, upperP, upperQ, upperR, uppers, upperT, upperU, upperV, 
upperW, upperX, upperY, upperZ, openBracket, backslash, closeBracket, 
circumflex, lowBar, grave, lowerA, lowerB, lowerC, lowerD, lowerE, lowerF, 
lowerG, lowerH, lower!, lowerJ, lowerK, lowerL, lowerM, lowerN, lowerO, 
lowerP, lowerQ, lowerR, lowerS, lowerT, lowerU, lowerV, lowerW, lowerX, 
lowerY, iowerZ, openBrace, vertical Bar, closeBrace, tilde, 
invertedExclamation(161), cent, poundSterling, dollar, yen, section(167), 
leftSingleQuote(l69), leftDoubleQuote, leftDoubleGuillemet, leftArrow, 
upArrow, rightArrow, downArrow, degree, plusOrMinus, superscript2, 
superscripts, multiply, micro, paragraph, centeredDot, divide, 
rightSingleQuote, rightOoubleQuote, rightDoubleGuillemet, oneQuarter, oneHalf, 
threeQuarters, invertedQuestionMark, graveAccent(193), acuteAccent, 
circumflexAccent, tildeAccent, macronAccent, breveAccent, overOotAccent, 
dieresisAccent, overRingAccent(202), cedilla, underline, doubleAcuteAccent, 
ogonek, hachekAccent, horizontal Bar, superscript!, registered, copyright, 
trademark, musicNote, oneEighth(220), threeEighths, fiveEighths, sevenEighths, 
ohmSign, upperAEdigraph, upperOstroke, feminineSpanishOrdinal, upperHstroke, 
upperlJdiagraph(230), upperLdot, upperLstroke, upperOslash, upperOEdiagraph, 
masculineSpanishOrdinal, upperThorn, upperTstroke, upperEng, lowerNapostrophe, 
lowerKgreenlandic, lowerAEdigraph, lowerOstroke, lowerEth, lowerHstroke, 
lowerldotless, lowerlJdiagraph, lowerLdot, lowerLstroke, lowerOslash, 
lowerOEdiagraph, lowerSzed, lowerThorn, lowerTstroke, lowerEng, escape}; 

Codesl64: -XCharSetlSA- type = machine oepend£nt{ 

kabu(33), maruA, marul, maruU, maruE, maruO, maruRo, maruHa, maruNi, maruHo, 
maruHe, maruTo, maruTi, maruRi, maruNu, reserved(255)}; 

Codes356: -XCharSet356-' type = machine dependent{ 

thlckSpace(33), fourEmSpace, hairSpace, punctuationSpace, decimalPoint(46), 
absoluteValue(124), similarTo(126), escape(255)}; 

Codes357: -XCharSet357- type = machine dependent{ 

nonBreakingSpace(33), nonBreakingHyphen, discretionaryHyphen, enDash, em Dash, 
fIgureDash, neutralQuote, loweredLeftOoubleQuote, germanRightOoubleQuote, 
guillemetLeftQuote, guillemetRlghtQuote, enQuad, emQuad, figureSpace, 
thinSpace, dagger, doubleOagger, bra, ket, rightPointinglndex, 
leftPointinglndex, leftPerp, nghtPerp, keft2Perp, right2Perp, 
leftWhiteLenticularBracket, rightWhiteLenticularBracket, nwArrow, seArrow, 
neArrow, swArrow, careOf, perThousand, muchLessThan, muchGreaterThan, 
notLessThan, notGreaterlhan, divides, doesNotOivide, parallel, notParallel, 
isAMemberOf, isNotAMemberOf, suchThat, doubieBackArrow, doubleOoubleArrow, 
doubleRightArrow, reversibleReaction2, reversibleReactionI, doubleArrow, 
curlyArrow, containsi, containedlnl, intersection, union, containsOrEquals, 
contained InOrEquals, contains2, containedln2, neitherConatainsNorlsEqualTo, 
neitherContainedlnNorlsEqualTo, doesNotContain, isNotContainedIn, 
checketBallotBox, nullSet, abstractPlus, abstractMinus, abstract Times, 
abstractDivide, centeredBullet, centeredRing, plancksConstant, litre, not, 
borkenV/erticalBar, angle, sphericalAngle, identifier, because, perpendicular, 
isProportionalTo, equivalent, equalByDefinition, questioned Equality, integral, 
contourintegral, approximatelyEquall, isomorphic, approximatelyEqual2, 
summation, product, root, minusOrPlus, shade, cruzeiro(161), florin, francs. 



D 



Listing of Public Symbols 



pesetas, europeanCurrency, milreis, genericlnfinity, number, take, tel, yogh, 0^ 

complexNumber, natural Number, realNumber, integer, leftCeiling, rightCeiling, 

leftFloor, rightFloor, therExists, forAII, and, or, qed, nabia, 

partial Derivative, ocrHook, ocrFork, ocrChair, alternatingCurrent, 

doubieLowBar, arc, romanNumerail, romanNumeralll, romanNumerallll, 

romanNumerallV, romanNumeralV, romanNumeralVI, romanNumeraiVII, 

rcmanNumeralVlil, romanNumerallX, romanNumeralX, spades, hearts, diamonds, 

clubs, checkMark, xMark, circled 1, circled2, circledS, circled4, circiedS, 

circled6, circled?, circledS, circled9, circled 10, circledRightArrow, 

circledRightThenOownArrow, circledDownThenLeftArrow, peaceSymboi, smileFace, 

poison, thickVerticalLine, thickHorizontalLine, thicklntersectingLines, 

thinVerticalLine, thinHorizontalLine, thinlntersectingLines, sun, 

firstQuarterMoon, thirdQuarterMood, mercury, jupiter, saturn,.uranus, neptune, 

pluto, aquarius, pisces, aries, taurus, gemini, cancer, leo, virgo, libra, 

scorpius, Sagittarius, Capricorn, telephone, oneThird, twoThirds, escape}; 

Codes360: -XC/iarSet360- TYPE s machine DePENOENT{ 

ligatureFF(33), ligatureFFI, ligatureFFL, ligatureFI, ligatureFL, ligatureFT, 
sigmaFinal(126), verticalTabGraphic(T84), tabGraphic, lineFeedGraphic, 
formFeedGraphic, carriageReturnGraphic, newLineGraphic, available276B, 
avaiiable277B, availabieSOOB, availableSOIB, pageFormatGraphic, 
startOfDocumentGraphic, stopGraphic, availabieSOSB, available306B, 
avaiiabie307B, available310B, avaiiable31 18, blackRectGraphic, 
checkerBoardGraphic, ibmOup, available315B, ibmFm, paraTabGraphic(217), 
available332B, availabie333B, available334B, newParagraphGraphic, 
available336B, available337B, avaHable340B, boxMT, boxNOT, boxEllipsis, 
boxRange, boxUpperX, boxUpperA, boxdigit9, boxUp'perZ, boxAsterisk, 
available352B, availabie353B, boxPlus, boxMinus, boxPeriod, boxComma, 
fieldFormatGreek(246), fieldFormatRussian, fieidFormatHiragana, 
fieldFormatKatakana, field FormatKanji, fieidFormatlapanese, spaceGraphicdot, 
spaceGraphicb, escape(255)}; 

Codes361 : -XCharSetSSI- type = machine oepenoent{ 

upperAgrave(33), upperAacute, upperAcircumflex, upperAtiide, upperAmacron, 
upperAbrev, upperAumlaut, upperAring, upperAogonek, upperCacute, 
upperCcircumflex, upperChighOot, upperCcedilla, upperChachek, upperDhachek, 
upperEgrave, upperEacute. upperEcircumflex, upperEmacron, upperEhighOot, 
upperEumlaut, upperEogonek, upperEhachek, upperGcircumflex(57), upperGbrev, 
upperGhighOot, upperGcedilla, upperHcircumfiex, upperlgrave, upperlacute, 
upperlcircumflex, upperltilde, upperlmacron, upperlhighOot, upperiumlaut, 
upperlogonek, upperJcircumflex, upperKcedilla, upperlacute, upperLcedilla, 
upperLhachek, upperNacute, upperNtilde, upperNcedilla, upperNhachek, 
upperOgrave, upperOacute, upperOcircumflex, upperOtilde, upperOmacron, 
upperOumlaut, upperODoubleAcute, upperRacute, upperRogonek, upperRhachek, 
upperSacute, upperScircumflex, upperScedilla, upperShachek, upperTcedilla, 
upperThachek, upperUgrave, upperUacute, upperUcircumflex, upperUtiide, 
upperUmacron, upperUbrev, upperUumlaut, upperUring, upperUDoubleAcute, 
upperUogonek, upperWcircumflex, upperYgrave, upperYacute, upperYcircumflex, 
upperYumlaut, upperZacute, upperZhighDot, upperZhachek, lowerAgrave(161), 
lowerAacute, lowerAcircumflex, lowerAtilde, lowerAmacron, lowerAbrev, jgg^ 
lowerAumlaut, lowerAring, lowerAogonek, lowerCacute, lowerCcircumfiex, 
lowerChighDot, lowerCcedilla, lowerChachek, lowerDhachek, lowerEgrave, 
lowerEacute, lowerEcircumflex, lowerEmacron, lowerEhighDot, lowerEumlaut, 
lowerEogonek, lowerEhachek, lowerGacute, lowerGcircumflex, lowerGbrev, 
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lowerGhighDot, lowerHcircumflex(189), lowerlgrave, lowerlacute, 
lowerlcircumflex, iowerltilde, towerlmacron, iowerlumlaut(196), lowerlogonek, 
lowerJcircumflex, iowerKcedilla, lowerLacute, lowerLcedilia, lowerLhachek, 
iowerNacute, lowerNtiide, iowerNcediiia, lowerNhachek, lowerOgrave, 
lowerOacute, lowerOcircumflex, lowerOtilde, lowerOmacron, lowerOumlaut, 
lowerODoubieAcute, lowerRacute, iowerRogonek, lowerRhachek, lowerSacute, 
lowerScircumfiex, lowerScedilla, lowerShachek, iowerTcediiia, iowerlhachek, 
lowerUgrave, lowerUacute, lowerUcircumflex, lowerUtilde, lowerUmacron, 
lowerUbrev, lowerUumiaut, lowerUring, lowerUOoubieAcute, lowerUogonek, 
lowerWcircumflex, lowerYgrave, lowerYacute, lowerYcircumflex, lowerYumlaut, 
lowerZacute, lowerZhighDot, lowerZhachek, escape(255)}; 

Codes41: -XC/»ar5et4 7- TYPE = machine depend£Nt{ 

kanjiSpace(33), japaneseComma, japanesePeriod, dakuonMark(43), handakuonMark. 
repeatHiragana(51), repeatHiraganaWithDakuon, repeatKatakana, 
repeatKatakanaWithDakuon, reduplicate, reduplicateAboveltem, repeatKanji, 
shime,.kanjiZero, longVowelBar, hyphen(62), parallelSign(66), 
threeDotLeader(68), twoDotLeader, ieftBrokenBracket(76), rightBrokenBracket, 
leftJapaneseQuote(86), rightlapaneseQuote, leftlapaneseOoubieQuote, 
rightlapaneseDoubleQuote, leftBlackLenticularBracket, 
rightBlackLenticularBracket, notEquai(98), lessThanOrEquaiTo(1 01), 
greaterThanOrEqualTo, infinity, therefore, male, female, minutes(108), 
seconds, degreesCelsius, whiteStar(121), blackStar, whiteCircle, blackCircle, 
bullsEye, whiteOiamond, escape(255)}; 

Codes42: -XCharSetAl- type = machine dependent{ 

biackDiamond(33), whiteSquare, blackSquare, whiteUpTriangle, blackUpTriangie, 
whiteDownTriangle, blackDownTriangie, jisKome, jisPostOffice, escape(255)}; 

Codes43: -XC/)arSet43- TYPE = machine dependent{ 

musical Flat( 172), soundRecordingCopyright(174), ayn(176), alifHamzah, 
lowerLeftQuote, musicalSharp(188), mjagkijZnak,tverdyjZnak, nsingTone(192), 
umlaut(201), highCommaOffCentre(203), highlnvertedComma, horn(206), 
hookToTheLeft(210), circleBelow(212), halfCircleBelow, dotBelow, 
doubieOotBeiow, doubleUnderiine(217), african Vertical Bar, circumflexUndermark, 
leftHalfOfLigature(221), rightHalfOfLigature, rightHalfOfDoubleTilda, 
escape(255)}; 

Codes44: -XCharSet44- type = machine oependent{ 

hirSmallA(33), hirA, hirSmalll, hirl, hirSmallU, hirU, hirSmallE, hirE, 
hirSmallO, hirO, hirKa, hirGa, hirKi, hirGi, hirKu, hirGu, hirKe, hirGe, 
hirKo, hirGo, hirSa, hirZa, hirSi, hirJi, hirSu, hirZu, hirSe, hirZe, hirSo, 
hirZo, hirTa, hirOa, hirTi, hirDi, hirSmalITu, hirTu, hirOu, hirTe, hirDe, 
hirTo, hirDo, hirNa, hirNi, hirNu, hirNe, hirNo, hirHa, hIrBa, hirPa, hirHi, 
hirBi, hirPi, hirHu, hirBu, hirPu, hirHe, hirBe, hirPe, hirHo, hirBo, hirPo, 
hirMa, hirMi, hirMu, hirMe, hirMo, hirSmallYa, hirYa, hirSmallYu, hirYu, 
hirSmallYo, hirYo, hirRa, hirRi, hirRu, hirRe, hirRo, hirSmallWa, hirWa, 
hirWi, hirWe, hirWo, hirN, escape(255)}; 

Codes45: -XCharSetAS- type = machine dependent{ 

katSmaliA(33), katA. katSmalll, kati, katSmallU, katU, katSmallE, katE, 
katSmallO, katO, katKa, katGa, katKi, katGi, katKu, katGu, katKe, katGe, 
katKo, katGo, katSa, katZa, katSi, katJi, katSu, katZu, katSe, katZe, katSo, 
katZo, katTa, katDa, katTi, katOi, katSmalITu, katTu, katDu, katTe, katDe, 
katTo, katDo, katNa, katNi. katNu, katNe, katNo, katHa, katBa, katPa, katHi, 
katBi, katPi, katHu, katBu, katPu, katHe, katBe, katPe, katHo, katBo, katPo, 
katMa, katlN/li, katMu, katMe, katMo, katSmallYa, katYa, katSmallYu, katYu, 
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katSmallYo, katYo, katRa, katRi, katRu, katRe, katRo, katSmallWa, katWa, 
katWi, katWe, katWo,.katN, katVu, katSmallKa, katSmalIKe, escape(255)}; 
Codes46: -XCharSetAB- type a machine oepenoent{ 

smootheBreathing(37), roughBreathing, iotaScript, upperPrime(52), lowerPrime, 
raisedPeriocl(59)« upperAipha(65), upperBeta, upperGamma(68), upperOelta, 
upperEpsilon, upperStigma, upperOigamma, upperZeta, upperEta, upperTheta, 
upperlota, upperKappa, upperLambda, upperMu, upperNu, upperXi, upperOmicron, 
upperPi, upperKoppa, upperRho, upperSigma, a 1 278, upperTau, upperUpsilon, 
upperPhi, upperKhi, upperPsi, upperOmega, upperSampi, lowerAlpha(97), 
lowerBeta, lowerBetaMiddleWord, lowerGamma, lowerOeita, lowerEpsilon, 
lowerStignrta, lowerDigamma, lowerZeta, lowerEta, lowerTheta, lowerlota, 
IcwerKappa, iowerLambda, iowerMu, lowerNu, lowerXi, lowerOmicron, lowerPi, 
lowerKoppa, lowerRho, lowerSigma, lowerSigmaMiddleWord, lowerTau, 
lowerUpsilon, lowerPhi, lowerKhi, lowerPsi, lowerOmega, lowerSampi, 
escape(255)}; 
Codes47: -XC/»arSet47- TYPE = machine dependent{ 

upperA(33), upperBe, upperVe, upperGe, upperDe, upperYe, upperYo, upperZhe, 
■ upperZe, upperl, upperlKratkoye, upperKa, upperEl, upperEm, upperEn, upperO, 
upperPe, upperEr, upperEs, upperTe, upperU, upperEf, upperXa, upperTse, 
upperChe, upperSha, upperShCha, upperTvyordiiZnak, upperYeri, 
upperMyaxkiiZnak, upperEOborotnoye, upperYu, upperYa, lowerA(81), lowerBe, 
lowerVe, lowerGe, lowerOe, lowerYe, lowerYo, lowerZhe, lowerZe, lowerl, 
lowerlKratkoye, lowerKa, lowerEI, lowerEm, lowerEn, lowerO, lowerPe, lowerEr, 
lowerEs, lowerTe, lowerU, lowerEf, lowerXa, lowerTse, lowerChe, lowerSha, 
lowerShCha, lowerTvyordiiZnak, lowerYeri, lowerMyaxkiiZnak, lowerEOborotnoye, 
lowerYu, lowerYa, escape(255)}; 
ColumnContents: -FileContainerSource— type = long descriptor for array 

CARDINAL OF ColumnContentslnfo; 
ColumnContentslnfo: -FUeContainerSource-' type = record ( 
info: select type: ColumnType from 
attribute = > [ 

attr: NSFile.AttributeType, 
formatProc: AttributeFormatProc "nil, 
needsOataHandle: boolean "false], 
extendedAttribute s > [ 

extended Attr : NSFi le. Extended Attri buteTy pe, 
formatProc: AttributeFormatProc 'nil, 
needsOataHandle: boolean >alse], 
muitipieAttributes = > [ 
attrs: NSFIIe.Seiections, 
formatProc: Multi AttributeFormatProc "nil, 
needsOataHandle: boolean "false], 
ENOCAse]; 

ColumnCount: -ContainerSource- ColumnCountProc; 
ColumnCountProc: -ContamerSource- type = procedure [source: Handle] 

RETURNS [columns: cardinal]; 
ColumnHeaderlnfo; --Conta/nerW/ndow-- type = record [ 

width: cardinal, wrap: boolean "true, heading: XString.ReaderBody]; 
ColumnHeaders: -ContainerWindow- type = long descriptor for array cardinal of 

ColumnHeaderlnfo; 
ColumnType: -f/VeConta/nerSource- type = { 

attribute. extendedAttribute, muitipieAttributes}; 
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CommandProc: -Form Window- TYPE = procedure [ 

window: Window.Handle, item: ItemKey, clientData: long pointer]; 
Compare: -XL/?ea/~ procedure [a: Number, b: Number] returns [Comparison]; 
Compare: -XString- procedure [ 

r1: Reader, r2: Reader, ignoreCase: boolean *true, 

sortOrder; SortOrder "standard] returns [Relation]; 
CompareStringsAndStems: '-XString- procedure [ 

r1 : Reader, r2: Reader, ignoreCase: boolean 'true, 

sortOrder: SortOrder "standard] 

returns [relation: Relation, equaiStems: boolean]; 
Comparison: -XLReal- type = {less, equal, greater}; 

compatibility: ~SWS>Attr/bute fypes- NSFile.ExtendedAttributeType = 10376B; 
Compose: -XMessage- procedure [ 

source: XString. Reader, destination: XString. Writer, args: StringArrayj; 
ComposeOne: -XMessage- procedure [ 

source: XString. Reader, destination: XString. Writer, arg: XString.Readerj; 
ComposeOneToFormatHandle: -XMessage- procedure [ 

source: XString, Reader, destination: XFormat.Handle, arg: XString.Reader]; 
ComposeToFormatHandle: -XMessage- procedure [ 

source: XString.Reader, destination: XFormat.Handle, args: StringArray]; 
ComputeEndContext: -XString- procedure [r: Reader] returns [c: Context]; 
ConfirmChoices: "Attent/on-- TYPE = record [ 

yes: XString.Reader, no: XString.Reader]; 
Conic: -Display- procedure [ 

window: Handle, a: long integer, b: long integer, c: long integer, 

d: long integer, e: long integer, errorTerm: long integer, 

start: Window.Place, stop: Window.Place, errorRef : Window.Place, 

sharpCornered: boolean, unboundedStart: boolean, unboundedStop: boolean, 

iineStyle: LineStyle 'nil, bounds: Window.BoxHandle "nil); 
containedln: -8WSAttr/bute fypes- NSFIie.ExtendedAttributeType = 10400B; 
Context: -XString- type = machine dependent record ( 

suffixSize(0:0..6): [1..21, 

homogeneous(0:7..7): boolean, 

prefix(0:8.. 1 5): Environment-ByteJ; 
Conversionlnfo: -Selection- type = record [ 

select type: * from 

convert = > null, 

enumeration s > [proc: procedure [Value] returns [stop: boolean]], 
query = > [query: long descriptor for array cardinal of QueryElement], 
endcase]; 

Dummy: definitions = 
begin 

Convert: -Selection- procedure [ 

target: Target, zone: uncounted zone *LOOPHOLE[0]] returns [value: Value]; 
Converter: -ProductF acton ngProducts-- Product = 7; 
Convert! nteger: -UnitConversion- procedure [ 

n: long integer, inputUnits: Units, outputUnits: Units] 

returns [long integer]; 
Convertltem: -ContainerSource-- Con vertltem Proc; 
Con vertltem Proc: -ContainerSource- type = procedure [ 

source: Handle, itemlndex: Itemlndex, n; cardinal 



D Listing of Public Symbols 



target: Selection.Target, zone: uncounted zone, 

info: Selection.Conversionlnfo *xxx, changeProc: ChangeProc 'nil, 

changeProcData: long pointer 'nil] returns [value: Selection. Value]; 
ConvertNumber: -Selection'- procedure [target: Target] 

RETURNS [ok: BOOLEAN, number: long unspecified]; 
ConvertProc: -Selection- type = procedure [ 

data: ManagerData, target: Target, zone: uncounted zone, 

info: Conversion Info *xxx] returns [value: Value]; 
ConvertReal: -UnitConversion- procedure [ 

n: XLReal. Number, inputUnits: Units, outputUnits: Units] 

returns (XLReal. Number]; 
Copy: -Selection- procedure (v: ValueHandle, data: long pointer]; 
CopyMove: -Selection- ValueCopyMoveProc; 
CopyOrMove: -Selection- type = {copy, move}; 
CopyReader: -XString- procedure [r: Reader, z: uncounted zone] 

returns [new: Reader]; 
CopyToNewReaderBody: -X5tr/ng- procedure [r: Reader, z: uncounted 
zone] 

RETURNS [ReaderBodyl; 
CopyToNewWriterBody: -XString- procedure [ 

r: Reader, z: uncounted zone, endContext: Context "unknownContext, 

extra: cardinal "0] returns [w: WriterBody]; 
Cos: -XLReal- procedure [radians: Number] returns [cos: Number]; 
coversheetOn: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 
10412B; 

CR: -XFormat- procedure (h: Handle "nil, n: cardinal * 1 ]; 

Create: -Catalog- procedure [ 

name: XString. Reader, catalog Type: NSFile.Type, 
session: NSFile.Session *LOOPHOLE[0]] returns [catalog: 

NSFile. Reference]; 

Create: --Conta/nerl/V/ndow- procedure ( 

window: Window.Handle, source: ContainerSource.Handle, 
columnHeaders: ColumnHeaders, firstltem: ContainerSource.ltemlndex "0] 

returns [ 

regularMenultems: MenuData.ArrayHandle, 

topPusheeMenu Items: MenuData.ArrayHandle]; 
Create: -ContainerWindowExtra- procedure [ 

window: Window.Handle, source: ContainerSource.Handle, 
columnHeaders: ContainerWindow.ColumnHeaders, 
firstltem: ContainerSource.ltemlndex '0, readonly: boolean "false] 
returns [ 

regularMenultems: MenuOata.ArrayHandle, 
topPusheeMenultems: MenuOata.ArrayHandie]; 
Create: -Context- procedure [ 

type: Type, data: Data, proc: DestroyProcType, window: Window.Handle]; 
Create: -FileContainerShell- procedure ( 

file: NSFile. Reference, columnHeaders: ContainerWindow.ColumnHeaders, 
col u m nContents: Fi I eContai nerSou rce. Col u m nContents, 
regularMenultems: Menu Data .Array Handle "xxx, 
topPusheeMenulterps: MenuData.ArrayHandle "xxx, scope: NSFile.Scope 

XXX, 

position: ContainerSource.ltemlndex '0, 

options: FileContainerSource.Options 'LOOPHOLE[0]] 



RETURNS [shell: StarWindowShell. Handle] 
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Create: -FHeContainerSource- procedure [ 

file: NS File. Reference, columns: ColumnContents, scope: NSFile.Scope *xxx, 
options: Options *LOOPHOLE[0]J returns [source: ContainerSource. Handle]; 

Create: --FormW'mdow- procedure [ 

window: Window.Handle, makeltemsProc: MakeltemsProc, 

layoutProc: LayoutProc *nil, windowChangeProc: GlobalChangeProc "nil, 

minDimsChangeProc: MinDimsChangeProc "nil, 

zone: uncounted zone "LOOPHOLEIOJ, clientOata: long pointer "nil]; 

Create: -MessageWindow- procedure ( 

window: Window.Handle, zone: uncounted zone "LOOPHOLE[0], 
lines: cardinal "10); 

Create: -PropertySheet- procedure [ 

formWindowltems: FormWindow.MakeltemsProc, menultemProc: MenultemProc, 
size: Window.Dims, menultems: Menultems "propertySheetDefaultMenu, 
title: XString.Reader "nil, pi aceToDi splay: Window.Place "nullPlace, 
formWindowltemsLayout: FormWindow. LayoutProc "nil, 
windowAttachedTo: StarWindowShell, Handle "LOOPHOLE[0], 
globalChangeProc: FormWindow.GlobalChangeProc "nil, display: boolean "true, 
clientData: long pointer "nil, afterTakenDownProc: MenultemProc "nil, 
zone: uncounted zone "LOOPHOLE[01] returns (shell: StarWindowShell. Handle]; 

Create: -Prototype- procedure ( 

name: XString.Reader, type: NSFile.Type, version: Version, 

subtype: Subtype "0, size: long cardinal "0, isDirectory: boolean "false, 

session: NSFile.Session " LOOPHOLE[0]] returns [prototype: NSFile.Handle]; 

Create: -StarWindowShell- procedure [ 

transitionProc: TransitionProc "nil, name: XString.Reader "nil, 

namePicture: XString. Character "0, host: Handle "LOOPHOLE(0], 

type: ShellType "regular, sleeps: boolean "false, 

considerShowingCoverSheet: boolean "true, 

currentlyShowingCoverSheet: boolean "false, 

pushersAreReadonly: boolean "false, readonly: boolean "false, 

scrollData: ScrollOata "vanillaScrollOata, 

garbageCollectBodiesProc: procedure [Handle] "nil, 

isCloseLegalProc: IsCIoseLegalProc *nil, bodyGravity: Window.Gravity nw, 

zone: uncounted zone "LOOPHOLE(0]] returns [Handle]; 

Create: -Window- procedure [ 

display: OisplayProc, box: Box, parent: Handle rootWindow, 

sibling: Handle "nil, child: Handle "nil, clearingRequired: boolean "true, 

windowPane: boolean "false, under: boolean "false, cookie: boolean "false, 

color: BOOLEAN "FALSE, zone: uncounted zone "LOOPHOLE[0]] 

returns [window: Handle]; 

CreateBody: -StarWindowShell- procedure [ 

sws: Handle, repaintProc: procedure [Window.Handle] "nil, 
bodyNotifyProc: TIP.NotifyProc "nil, box: Window.Box "xxx] 
returns [Window.Handle]; 

CreateCharTable: -TIP- procedure [ 

z: UNCOUNTED zone "LOOPHOLE(0], buffered: boolean "true] 
RETURNS [table: Table]; 

CreateOesktop: -StarOes/ctop- procedure [name: XString.Reader] 
RETURNS [fh: NSFile.Handle]; 

CreateFleld: -SimpleTextEdit- procedure [ 

clientData: long pointer, context: FieldContext, dims: Window.Dims, 
initString: XString.Reader "nil, 

flushness: SimpleTextDisplay.Flushness "fromFirstChar, 
streakSuccession: SimpleTextDisplay.StreakSuccession "fromFlrstChar, 
readonly: boolean "false, password: boolean "false. 
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fixedHeight: BOOLEAN "false, font: SimpleTextFontMappedFontHandle "nil, 
backing Writer: XString. Writer "nil, 

SPEClALKeyboard: BlackKeys. Keyboard "nil] returns [f: FieldJ; 
CreateFieidContext: -SimpleTextEdit" procedure ( 

z: uncounted zone, window: Window.Handle, changeSizeProc: ChangeSizeProc] 

RETURNS [fc: FieidContextl; 
CreateFiie: -Catalog- procedure [ 

catalogType: NSFiie.Type "10476B, name: XString. Reader, type: NSFile.Type, 

isDirectory: boolean "false, size: long cardinal "0, 

session: NSFile.Session "LOOPHOLEIOJ] returns [file: NSFile.Handie]; 
Createitem: -MenuData- procedure [ 

zone: uncounted zone, name: XString. Reader, proc: A/lenuProc, 

itemOata: long unspecified "0] returns [itemHandle]; 
CreateLlnked: -PropertySheet- procedure [ 

formWindowltems: FormWindow.MakeltemsProc, menultemProc: MenultemProc, 

size: Window.Dims, menultems: iVIenultems "propertySheetDefaultMenu, 

title: XString.Reader "nil, placeToOisplay: Window.Place "nullPlace, 

formWindowltemsLayout: FormWindow.LayoutProc "nil, 

windowAttachedTo: StarWindowShell. Handle "LOOPHOLEIO], 

globalChangeProc: FormWindow.GlobalChangeProc "nil, display: boolean 'true, 

linkWindowltems: FormWindow.MakeltemsProc, 

linkWindowltemsLayout: FormWindow.LayoutProc "nil, 

clientData: long pointer "nil, afterTakenDownProc: MenultemProc "nil, 

zone: uncounted zone "LOOPHOLE[0]] returns [shell: StarWindowShell. Handle); 
CreateMenu: -MenuData- procedure [ 

zone: uncounted zone, title: ItemHandle, array: ArrayHandle, 

copyltemslntoMenusZone: boolean "false] returns [Menu Handle]; 
CreatePeriodicNotify: -TIP- procedure [ 

window: Window.Handle "nil, results: Results, milliseconds: cardinal, 

notifyProc: NotifyProc "nil] returns [PeriodicNotIfy]; 
CreatePlaceHolderTable: ~r/P- procedure [z: uncounted zone "LOOPHOLE[0]] 

RETURNS [table: Table]; 
CreateProcType: -Context- type = procedure returns [Data, DestroyProcTypej; 
CreateTable: -TIP- procedure [ 

file: XString.Reader, z: uncounted zone 'LOOPHOLE[0], 

contents: XString.Reader "nil] returns (table: Table]; 
Current: -XTime- procedure returns (time: System. Greenwich Mean Time]; 
DashCnt: -Display- cardinal s 6; 

Data: -Conta/nee- type = record [reference: NSFi I e. Reference "xxx]; 

Data: -Context- type = long pointer; 

DataHandle: -Containee- type = long pointer to Data; 

Date: -XFormat- procedure ( 

h: Handle "nil, time: System. GreenwichMeanTime "LOOPHOLE(1760131 1200B], 

format: DateFormat "dateAndTime]; 
dateAndTime: -XTime- XString.Reader; 
DateColumn: -FHeContainerSource- procedure 

returns [multipleAttributes ColumnContentslnfo]; 
DateFormat: -XFormat- TYPE = {dateOnly,timeOnly, dateAndTime}; 
dateOnly: -XTime- XString.Reader; 

DaysOfWeek: -XComSo/tMessage- type = Keys (monday..sunday]; 
Decase: -XChar- procedure (c: Character] returns (Character]; 
Decimal: -XFormat- procedure [h: Handle "nil, n: long integer]; 
Decimal: -XToken- procedure [h: Handle, signal On Error: boolean 'true] 

returns (i: LONG integer]; 
DecimalFormat: -XFormat- NumberFormat;' 
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Decompose: -XA/fessage- procedure (source: XString. Reader] 

RETURNS (args: StringArrayJ; 
DefaultFileConvertProc: -Containee-- Selection.ConvertProc; 
defaultGeometry: "KeyboardWindow- BlackKeys-Geometry Table; 
DefaultLayout: -FormWindow- LayoutProc; 
defaultPicture: -KeyboardWindoW" BlackKeys.Picture; 
DefaultPictureProc: -KeyboardWindQw- BlackKeys.PictureProc; 
defaultTabStops: -FormWindow- TabStops; 
defaultTime: -XTime- System. GreenwichMeanTi me; 
Defined: -Cursor- TYPE = Type[blank..columnl; 
DeleteAll: -ancfo-- procedure; 

DeleteAndShowNextPrevious: "ContainerWindow- procedure [ 

window: Window.Handle, item: ContainerSource.ltemlndex, direction: Direction]; 
DeleteAndShowNextPrevious: -ContainerWindowExtral" procedure [ 

window: Window. Handle, item: ContainerSource.ltemlndex, 

di rection : Contai nerWi ndow. Di recti on] 

RETURNS [newOpenShelt: StarWindowShel I. Handle]; 
Deleteltems: -Contai nerSource- DeleteltemsProc; 
DeleteltemsProc: -Contai nerSource-- type = procedure [ 

source: Handle, itemlndex: Itemlndex, n: cardinal 

changeProc: ChangeProc "nil, changeProcData: long pointer "nil]; 
DeleteNltems: -ContainerCache- procedure ( 

cache: Handle, item: cardinal, nitems: cardinal "1]; 
Delimited: -XToken- FilterProcType; 
Dependency: --Event- type [2]; 

Dereference: -XString- procedure (r: Reader] returns [rb: ReaderBody]; 
DescribeOption: -ProductFactoring- procedure [ 

option: Option, desc: XString.Reader, 

prerequisite: Prerequisite "nullPrerequisite]; 
DescribeProduct: -ProductFactoring- procedure [ 

product: Product, desc: XString.Reader]; 
DescribeReader: -XString- Courier. Description; 
DescribeReaderBody: -XString- Courier. Description; 
desktop: -awSF/Vefypes- NSFile.Type = 10400B; 
desktopCatalog: ~flWSF//erypes-NSFile.Type = 10400B; 
DesktopProc: -IdieControl- type = procedure; 
desktopWindowAvailable: -StarOesktop- Atom.ATOM; 
DestailBody: -5tarlV/ndow5/)e//~ procedure [body: Window.Handle]; 
Destroy: -ContainerWindow- procedure [Window.Handle]; 
Destroy: -Context- procedure [type: Type, window: Window.Handle]; 
Destroy: -FormWindow- procedure [window: Window.Handle]; 
Destroy: -MessageWindow- procedure [Window.Handle]; 
Destroy: -StarWindowShell- procedure [sws: Handle]; 
DestroyAll: -Context- procedure [window: Window.Handle]; 
DestroyBody: -StarWindowShell- procedure [body: Window.Handle]; 
DestroyFieid: -SimpleTextEdit- procedure [f: Field]; 
DestroyFieidContext: -SimpleTextEdit- procedure [fc: Field Context]; 

END. 



Destroyltem: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, repaint: boolean *true]; 
Destroyltem: -MenuData- procedure [zone: uncounted zone, item: ItemHandle]; 
Destroyitems: -FormWindow- procedure ( 

window: Window.Handle, item: long descriptor for array cardinal of ItemKey, 

repaint: boolean "true]; 
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OestroyMenu: -MenuData- procedure (zone: uncounted zone, menu: MenuHandleJ; 

Destroy Messages: -XMessage- procedure [h: Handle]; 

Destroy MsgsProc: -XMessage-- type = procedure [clientData: ClientDataJ; 

DestroyProcType: -Context- type = procedure (Data, Window.Handle]; 

DestroyTable: -f/P- procedure (long pointer to Table); 

DFonts: -ProductFactoringProductS" Product = 3; 

Difficulty: ~Se/ect/on~ type = {easy, moderate, hard, impossible}; 

Digit: -XiReai- type = (0..91; 

Digits: -XZ./?ea/- type = packed array (0.. 12] of Digit; 

Dims: -Window- type = record (w: integer, h: integer]; 

Direction: -Conta/nerW/ndow- type = {next, previous}; 

Discard: Selection- procedure [saved: Saved, unmark: boolean 'true]; 

DisplayProc: -Window-iYPE = procedure (window: Handle]; 

Divide: -XL/?ea/~ procedure (a: Number, b: Number] returns (Number]; 

DoAnUndo: -Undo- procedure; 

DoAnUnundo: -Undo- procedure; 

DoneLookingAtTextltemValue: -FormWindow- procedure ( 

window: Window.Handle, item: Item Key]; 
DoneWithString: -Atom icPro file- procedure (string: XString.Reader]; 
dontTimeout: -Attention- Process. Ticks » 0; 
DoTheGreeterProc: -IdleControl- GreeterProc; 
Double: -XLReal- procedure (Number] returns (Number]; 
Down U p: ~leve//VAf eys- TYPE = Keystations. DownUp; 
Down U p: -r/P- type = LevellVKeys.DownUp; 
DstFunc: -0#sp/ay- TYPE = BitBlt.DstFunc; 
E: -XiPea/- PROCEDURE returns (Number]; 
Editlnfo: -ContainerSource- type = record ( 

afterltem: Itemlndex, nitems: cardinal]; 
Ellipse: -Display- procedure ( 

window: Handle, center: Window.Place, xRadius: integer, yRadius: integer, 

lineStyie: LineStyle 'nil, bounds: Window.BoxHandle 'nil]; 
Empty: -XString- procedure (r: Reader] returns (boolean]; 
emptyContext: -XString- Context; 
Enabled: -ProductFactoring- procedure (option: Option] 

returns (enabled: boolean]; 
EntireBox: -Window- procedure [Handle] returns [box: Box); 
EntryEnumProc: -OptionFile- type = procedure (entry: XString.Reader] 

returns [stop: boolean 'false]; 
Enumerate: -Catalog- procedure [proc: CatalogProc]; 
Enumerate: -Selection- procedure [ 

proc: EnumerationProc, target: Target, data: RequestorData 'nil, 

zone: uncounted zone 'LOOPHOLE(0]] returns [aborted: boolean]; 
EnumerateAllMenus: -StarWindowShell Extra- procedure ( 

sws: StarWindowShell. Handle, proc: StarWindowShell. MenuEnumProc]; 
EnumerateOlsplayed: ~StarW/ndowS/»e//-- procedure [proc: ShellEnumProc] 

RETURNS (Handle 'LOOPHOLE[0]1; 
EnumerateDisplayedOflype: -StarWindowShell- procedure ( 

type: ShellType, proc: ShellEnumProc] returns (Handle 'LOOPHOLE(0]]; 
EnumerateEntries: -OptionFile- procedure ( 

section: XString. Reader, callBack: EntryEnumProc, 

file: NSFi I e. Reference 'xxx]; 
EnumeratelnvalidBoxes: -W/ndow- procedure [window: Handle, proc: BoxEnumProcj; 
EnumerateKeyboards: -KeyboardKey- procedure [ 

class: KeyboardClass, enumProc: EnumerateProc]; 
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EnumerateMyOisplayedParasites: StarWindowShell- procedure [ 

sws: Handle, proc: ShellEnumProcJ returns [Handle "LOOPHOLE[0l]; 
EnumeratePopupMenus: -StarWindowShell" procedure [ 

sws: Handle, proc: MenuEnumProc]; 
EnumerateProc: -KeyboardKey- type = procedure [ 

keyboard: BtackKeysXeyboard, class: KeyboardClass] 

returns [stop: boolean "false]; 
EnumerateSections: -OptionFiie-- procedure ( 

callBack: SectionEnumProc, file: NSFile. Reference "xxx]; 
EnumerateString: -AtomicProfile- procedure ( 

atom: Atom.ATOM, proc: procedure (XString. Reader]]; 
EnumerateTree: -Window- procedure [ 

root: Handle, proc: procedure (window: Handle]]; 
EnumerationProc: -Selection- type = procedure [ 

element: Value, data: RequestorData] returns [stop: boolean "false]; 
Equal: -XLHea/- procedure [a: Number, b: Number] returns [boolean]; 
Equal: -XStr/ng- procedure [r1: Reader, r2: Reader] returns [boolean]; 
Equivalent: -XString- procedure {r1 : Reader, r2: Reader] returns [boolean]; 
eraseFlags: -Display- BitBltFlags; 
Error: -Containee- error ( 

msg: XString.Reader "nil, error: error "nil, errorOata: long pointer "nil]; 
Error: -ContainerSource- error [ 

code: ErrorCode, msg: XString.Reader "nil, error: error "nil, 

error Data: long pointer "nil]; 
Error: -ContainerWindow- error [code: ErrorCode]; 
Error: -Context- error [code: ErrorCode]; 
Error: -FormWindow- error [code: ErrorCode]; 
Error: -KeyboardKey- error [code: ErrorCode]; 
Error: -OptionFile- error [code: ErrorCode); 
Error: -ProductFactoring- error (type: ErrorType]; 
Error: -PropertySheet- error [code: ErrorCode]; 
Error: -Selection- error (code: ErrorCode]; 
Error: -SimpleTextEdit- error [type: ErrorType]; 
Error: -StarWindowShell- error [code: ErrorCode]; 
Error: -TIP- error [code: ErrorCode]; 
Error: -Window- error [code: ErrorCode]; 
Error: -XFormat- error [code: ErrorCode]; 
Error: -XLReal- error (code: ErrorCode]; 
Error: -XMessage- error [type: ErrorType]; 
Error: -XString- error (code: ErrorCode]; 
ErrorCode: -<ontainerSource- type = machine dependent{ 

invalidParameters, accessError, fileError, noSuchltem, other, last(15)}; 
ErrorCode: -ContainerWindow- type = machine dependent{ 

notAContainerWindow, noSuchltem, last(7)}; 
ErrorCode: -Context- type = {dupiicateType, windowlsNIL, tooManyTypes, other}; 
ErrorCode: -FormWindow- type = machine D£PENDENt{ 

notAForm Window, wrongltemType, invalidChoiceNumber, noSuchLine, 

alreadyAForm Window, invalid Item Key, itemNotOnLine, duplicateltemKey, 

incompatibieLayout, alreadyLaidOut, last(15)}; 
ErrorCode: -KeyboardKey- type = { 

alreadylnSystemKeyboards, notlnSystemKeyboards, insufficientSpace}; 
ErrorCode: -OptionFile- type = { 

invalidParameters, inconsistentValue, notFound, syntaxError}; 
ErrorCode: -PropertySheet- type = {notAPropSheet}; 
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ErrorCode: -Selection- type = { 

tooManyActions, tooManyTargets, invaiidOperation, operationFailed, didntAbort, 

didntCIear}; 
ErrorCode: -StarWindowShell- TYPE = { 

desktopNotUp, notASWS, notStarStyle, tooManyWindows}; 
ErrorCode: -f/P- TYPE = {noSuchPeriodlcNotifief, other}; 
ErrorCode: -Window- type = { 

illegaiBitmap, iiiegai Float, windowNotChildOf Parent, whosSlidingRoot, 

noSuchSibiing, noUnderVariant, windowlnTree, sizingWithBitmapUnder, 

iilegaiStack, invalidParameters}; 
ErrorCode: -Xformaf- type = {invalidFormat, nilData}; 
ErrorCode: --XZ./?ea/- type = { 

bug, divideByZero, invaiidOperation, notANumber, overflow, underflow, 

unimplemented}; 
ErrorCode: -XStr/ng- TYPE = { 

invaiidOperation, multipleCharSets, tooManyBytes, invalidParameter}; 
ErrorType: -ProductFactoring- type = { 

dataNotFound, notStarted, illegalProduct, illegalOption, missingProduct, 

missingOption}; 
ErrorType: -SimpleTextEdit- type = { 

fieldlsNoplace, noRoom In Writer, lastCharGTfirstChar}; 
ErrorType: -XMessage- type = { 

arrayMismatch, invaiidMsgKeyList, invalidStringArray, invalidString, 

notEnoughArguments}; 
EventData: ~App//cat/onFo/der-- TYPE = record ( 

applicationFoider: NSFile. Reference, internal Name: XString. Reader]; 
EventType: -f venf- type = Atom. atom; 
Exp: -XLReal- procedure [Number] returns [Number]; 
ExpandWrlter: -XString- procedure [w: Writer, extra: cardinal]; 
Fetch: -Cursor- procedure (h: Handle]; 

FetchFromType: -Cursor- procedure [h: Handle, type: Defined]; 

Field: -SimpleTextEdit- type = long pointer to FieldObject; 

FieldContext: -SimpleTextEdit- type = long pointer to FieldContextObject; 

FieldContextObject: -SimpleTextEdit- type; 

FieldObject: -SimpleTextEdit- type; 

fifty Percent: -Display- Brick; 

filedrawerReference: -BWSAttributeTypes- NSFile.ExtendedAttributeType = 
10407B; 

FillProc: -ContainerCache- type = procedure (cache: Handle] 

returns [errored: boolean 'false]; 
FillResolveBuffer: -SimpleTextDisplay- procedure [ 

string: XString. Reader, lineWidth: cardinal "177777B, 

wordBreak: boolean "TRuE,streakSuccession: StreakSuccession 'fromFirstChar, 

resolve: ResolveBuffer, font: SimpleTextFontMappedFontHandle "nil] 

RETURNS [width: cardinal, result: Result, rest: XString. ReaderBody]; 
Filtered: -XToken- procedure [ 

h: Handle, data: FilterState, filter: FilterProcType, 

skip: SkipMode 'whiteSpace, temporary: boolean "true] 

RETURNS [value: XString. ReaderBody]; 
FilterProcType: -XToAfen- type = procedure [ 

c: XChar. Character, data: FilterState] returns [inClass: boolean]; 
FilterState: -xro/cen- type = long pointer to Standard FilterState; 
Find: -Context- procedure [type: Type, window: Window.Handle] returns [Data]; 
Find: -Prototype- procedure [ 

type: NSFile.Type, version: Version, subtype: Subtype "0, 

session: NSFile. Session ''LOOPHOLE[0l] returns [reference: NSFile.Reference]; 
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FindDescriptionFile: -AppUcationFolder- procedure [ 

applicationFoider: NSFile. Handle] returns [descriptionFiie: NS File. Reference] ; 
FindOrCreate: -Context-- procedure [ 

type: Type, window: Window. Handle, createProc: CreateProcType] returns [Data]; 
First: -XString-' procedure [r: Reader] returns (c: Character]; 
firstAvai labieApplicationType: -BWSAtthbuteTypes- 

NSFile. ExtendedAttributelype 3 10505B; 
firstBWSType: -flWSAttr/buterypes- NSFile. ExtendedAttributelype = 10400B; 
f i rstOld AppI i cati onSpeci f i c : -BWSAttributeTypes-- 

NSFile. ExtendedAttributelype 3 104148; 
firstSpareSWSType: -flWSAttr/daterypes- NSFile. ExtendedAttributelype = 104618; 
firstStarType : --awSf/Verypes-- NSFile.Type = 104008; 
Fix: "XLReal- procedure [Number] returns [long integer]; 
FixdPtNum: -0«p/ay- type = machine dependent record [ 

select overlaid * FROM 

wholeThing = > [li(0:0..31): long integer], 

parts a > [frac(0:0..15): cardinal, int(1:0..15): integer], 

endcase]; 

Float: -W/ndow- procedure [window: Handle, temp: Handle, proc: FloatProc]; 

Float: -XL/?ea/~ procedure [long integer] returns [Number]; 

FloatProc: -Window- type = procedure [window: Handle] 
returns [place: Place, done: boolean]; 

Flushness: -Form Window- TYPE « SimpleTextDisplay.Flushness; 

Flushness: -SimpleTextDispiay- type = {flushLeft, flushRight, fromFirstChar}; 

FlushUserinput: -TIP- procedure; 

FocusTakeslnput: -TIP- procedure returns [boolean]; 

FontNotFound: -SimpleTextFont- signal [name: XString. Reader]; 

Format: -XTime- procedure [ 

xfh: XFormatHandle "NIL, time: System.GreenwichMeanTime 'defaultTime, 
template: XString.Reader "dateAndTime, Itp: LTP "useSystem]; 

formatHandle: -Attention- XFormat. Handle; 

FormatProc: -Xformat- type = procedure [r: XString.Reader, h: Handle]; 
FormatReal: -XLReal- procedure [ 

h: XFormat. Handle "nil, r: Number, width: natural]; 
FractionPart: -XLReal-^ procedure [Number] returns [Number]; 
Free: -Selection- procedure [v: ValueHandle]; 

Free: -W/ndow- procedure [window: Handle, zone: uncounted zone "LOOPHOLE(0]]; 
FreeBadPhosphorList: -Window- procedure [window: Handle]; 
FreeCache: -ContainerCache- procedure [Handle]; 
FreeChoiceHintsProc: -FormWindow- type = procedure [ 

window: Window. Handle, item: Item Key, 

hints: long descriptor for array cardinal of Choicelndexj; 
FreeChoiceitems: -FormWindowMessageParse- procedure [ 

choiceltems: FormWindow.Choiceitems, zone: uncounted zone]; 
FreeContext: -Selection- procedure [v: ValueHandle, zone: uncounted zone]; 
FreeDataProcedure: -Event- type = procedure [myData: long pointer]; 
FreeMark: --Conta/nefCac/»e~ procedure [mark: Mark]; 

FreeMsgOomainsStorage: --XMessage- procedure [msgDomains: MsgDomains]; 
FreeReaderBytes: -XString- procedure [r: Reader, z: uncounted zone]; 
FreeReaderHandle: --XTo/cen-- procedure [h: Handle] returns [nil: Handle]; 
FreeResolveBuffer: -SimpleTextDisplay- procedure [ResolveBufferj; 
FreeStd: -Selection- ValueFreeProc; 

FreeStreamHandle: -XToken- procedure [h: Handle] returns [s: Stream. Handle]; 



D 



Listing of Public Symbols 



FreeTextHintsProc: -FormWindow- type = procedure ( jUl 

window: Window. Handle, item: ItemKey, 

hints: long descriptor for array cardinal of XString.ReaderBodyJ; 
FreeTokenString: -XTo/lce/i- procedure [r: XString. Reader] 

returns [nil: XString. Reader 'nil]; 
FreeTree: -Window- procedure [ 

window: Handle, zone: uncounted zone UOOPHOLE(0]]; 
FreeWriterBytes: "XString- procedure (w: Writer]; 
FromBiock: -XString- procedure { 

block: EnvironmentBlock, context: Context ^vanillaContext] 

returns [ReaderBody]; 
FromChar: -XString- procedure [char: long pointer to Character] 

returns [ReaderBody]; 
FromName: ~/App//catfonFo/der- procedure [internal Name: XString. Reader] 

RETURNS (applicationFolder: NS File. Reference]; 
FromNSString: -XString- procedure [ 

s: NSString.String, homogeneous: boolean 'false] returns [ReaderBody]; 
FromSTRING: -XStr/ng- procedure [s: long string, homogeneous: boolean "false] 

returns [ReaderBody]; 
fullUserName: -StarDesktop- Atom.ATOM; 
GenericProc: -Containee- type = procedure [ 

atom: Atom.ATOM, data: DataHandle, changeProc: ChangeProc 'nil, 

changeProcData: long pointer 'nil] returns [long unspecified]; 
Geometry Table: -BlackKeys- type = long pointer; 
GeometryTableEntry: -KeyboardWindow- type = record ( 

box: Box, key: KeyStations, shift: ShiftState]; _ 
Get: -XMessage- procedure [h: Handle, msgKey: MsgKey] 

RETURNS [msg: XString. ReaderBody]; 
GetAdjustProc: -StarWindowShell- procedure (sws: Handle] returns [AdjustProc]; 
GetAvailableBodyWindowOims: -StarWindowShell- procedure [sws: Handle] 

returns [Window. Dims]; 
GetBitmapUnder: -W/ndow- procedure [window: Handle] returns [long pointer]; 
GetBody: -StarWindowShell- procedure [sws: Handle] returns [Window.Handle]; 
GetBodyWindowJustFits: -StarWindowShell- procedure [sws: Handle] 

RETURNS [boolean]; 

GetBOOLEAN: -AtomicProfile- procedure [atom: Atom.ATOM] returns [boolean]; 
GetBooieanltemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey] returns [value: boolean]; 
GetBooleanValue: -OptionFile- procedure [ 

seaion: XString. Reader, entry: XString. Reader, file: NSFile.Reference 'xxx] 

RETURNS [value: boolean]; 
GetBox: -SimpleTextEdit- procedure [f: Field] returns [box: Window.Box]; 
GetBox: -Window- procedure [Handle] returns [box: Box]; 
GetCachedName: -Containee- procedure [data: DataHandle] 

returns [name: XString. ReaderBody, ticket: Ticket]; 
GetCachedType: -Containee- procedure [data: DataHandle] 

returns [type: NSFile.Typej; 
GetCaretPlace: -SimpleTextEdit- procedure [context: FieldContext] 

RETURNS (place: Window.Place]; 
GetCharProcType: --XTo/fen-- type = procedure [h: Handle] 

RETURNS [c: XChar.Character]; 
GetCharTranslator: -TIP- procedure [table: Table] returns [o: CharTranslator]; ^gj^ 
GetCharWIdth: -S/mp/erextD/sp/ay- PROCEDURE [ 

char: XChar.Character, font: SimpleTextFont.MappedFontHandle 'nil] 

RETURNS [width: cardinal]; 
GetChild: -Window- procedure [Handle] returns [Handle]; 
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GetChoiceltemValue: -FormWindow- procedure [ 

window: Wmdow.Handle, item: ItemKeyJ returns [value: Choicelndex]; 
GetClearingRequired: --Window- procedure [Handle] returns [boolean]; 
GetCiientData: -FormWindow- procedure [window: Window.Handie] 

returns [dientOata: long pointer]; 
GetCiientData: -SimpleTextEdit- procedure [f: Field] 

returns [clientData: long pointer]; 
GetContatnee: -StarWindowShellr- procedure [sws: Handle] 

returns [Cental nee. Data]; 
GetContainerSource: -FileContainerShell- procedure [ 

shell: StarWindowShell. Handle] returns [source: ContainerSource. Handle]; 
GetContainerWindow: -F'tleContamerShell- procedure [ 

shell: StarWindowShell. Handle] returns [window: Window.Handie]; 
GetCurrentDesktopFlie: -StarDesktop'- procedure returns [NSFile. Reference]; 
GetCurrentKeyboard: -BlackKeys- procedure returns [current: Keyboard]; 
GetDecimailtemValue: -FormWindow- procedure [ 

window: Window.Handie, item: ItemKey] returns [value: XLReal. Number]; 
GetDefaultlmplementation: -Containee-- procedure returns [Implementation]; 
GetDesktopProc: --IdieControi- procedure [atom: Atom.ATOM] 

returns [DesktopProc]; 
GetDims: -Window- procedure [Handle] returns [dims: Dims]; 
GetDisplayProc: -Window- procedure [Handle] returns [DisplayProc]; 
GetDisplayWindow: -KeyboardWindow- procedure returns [Window.Handie]; 
GetFieldContext: -SimpleTextEdit- procedure [f : Field] returns [FieldContext]; 
GetFile: -Catalog- procedure [ 

catalogType: NSFile.Type *10476B, name: XString. Reader, 

readonly: boolean "false, session: NSFile.Session *LOOPHOLE[0]] 

RETURNS [file: NSFile.Handle]; 
GetFtushness: --Form W/ndow- procedure [window: Window.Handie, item: ItemKey] 

RETURNS [old: Flushness]; 
GetFlushness: -SimpleTextEdit- procedure [f : Field] 

RETURNS [SimpleTextDisplay.Flushness]; 
GetFont: -SimpleTextEdit- procedure [f: Field] 

RETURNS [SimpleTextFontMappedFontHandle]; 
GetFormWindows: -PropertySheet- procedure [shell: StarWindowShell. Handle] 

RETURNS [form: Window.Handie, link: Window.Handie]; 
GetGlobaiChangeProc: -FormWindow- procedure [window: Window.Handie] 

RETURNS [proc: Global ChangeProc]; 
GetGreeterProc: -IdleControl- procedure returns [GreeterProc]; 
GetHandie: -XComSoftMessage- procedure returns [h: XMessage.Handle]; 
GetHost: -StarW/ndowS/ie//~ procedure [sws: Handle] returns [Handle]; 
Getimplementation: -Conta/nee- procedure [NSFile.Type] 

RETURNS [Implementation]; 
Getimplementation: -Undo- procedure returns [Implementation]; 
Getlnfo: -Cursor- procedure returns [info: Info]; 

GetlnputFocus: -S/mp/erextfd/t- procedure [fc: FieldContext] returns [Field]; 
GetlnputFocus: -TIP- procedure returns [Window.Handie]; 
GetlntegerltemValue: -FormWindow- procedure [ 

window: Window.Handie, item: ItemKey] returns [value: long integer]; 
GetlntegerValue: -OptionFile- procedure [ 

section: XString. Reader, entry: XString. Reader, index: cardinal *0, 

file: NSFile.Reference 'xxx] returns [value: long integer]; 
GetlsCloseLegalProc: -StarWindowShell- procedure [sws: Handle] 

RETURNS [IsCloseLegalProc]; 
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Getlteminfo: -FileContainerSource- procedure [ 

source: ContainerSource.Handle, itemlndex: ContainerSource.ltemlndex] 

RETURNS [file: NSFile. Reference, type: NSFIIe.Type]; 
GetloinDirection: -XChar- procedure [Character] returns [JoinOirection]; 
GetLength: -ContainerCacheExtra- procedure [cache: ContainerCache.Handle] 

RETURNS [cacheLength: cardinal]; 
GetLength: -ContainerSource-- GetLengthProc; 
GetLengthProc: -ContainerSource- type = procedure [source: Handle] 

RETURNS [length: cardinal, totalOrPartial: TotalOrPartial "total]; 
GetLlmitProc: -StarWindowShell- procedure [sws: Handle] returns [LimitProc]; 
GetList: -XMessage- procedure [ 

h: Handle, msgKeys: MsgKeyList, msgs: StringArray]; 
GetLONGINTEGER: -AtomicProfUe- procedure [atom: Atom.ATOM] 

returns [long integer]; 
GetManager: -TIP- procedure returns [current: Manager]; 
GetMode: -TlPStar- procedure returns [mode: Mode]; 
GetMultipleChoiceltemValue: -FormWindow- procedure [ 

window: Window. Handle, item: ItemKey, zone: uncounted zone] 

RETURNS [value: long descriptor for ARRAY CARDINAL OF ChoicelndexJ; 
GetNextAvailableKey: -FormWindow- procedure [window: Window. Handle] 

RETURNS [key: ItemKey]; 
GetNextOutOfProc: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey] returns [NextOutOfProc]; 
GetNextUnobscuredBox: -StarDesktop- procedure [height: integer] 

RETURNS [Window. Box]; 
GetNotifyProc: - HP- procedure [window: Window.Handle] returns [NotifyProc]; 
GetNotifyProcFromTable: -TIP- procedure [table: Table] returns [NotifyProc]; 
GetNthltem: ~ContamerCac/je~ procedure [cache: Handle, n: cardinal] 

returns [Item Handle]; 
GetOpenitem: -ConfamerW/ndow— procedure [window: Window.Handle] 

returns [item: ContainerSource. Item Index * 1 77777BJ; 
GetPane: -Window- procedure [Handle] returns [boolean]; 
GetParent: -Window- procedure [Handle] returns [Handle]; 
GetPlace: -r/P- procedure [window: Window.Handle] returns (Window. Place]; 
GetPlaceFromReference: -StarDeslftop- procedure [ref: NSFile. Reference] 

returns (Window. PI ace]; 
GetPName: -Atom- procedure [atom: atom] returns [pName: XString.Readerj; 
GetProp: -Atom- procedure [onto: atom, prop: atom] returns [pair: RefPair]; 
GetPusheeCommands: -StarWindowShell- procedure [sws: Handle] 

RETURNS [ 

bottom: MenuOata.MenuHandle, middle: MenuOata.MenuHandle, 

top: MenuOata.MenuHandle]; 
GetReadOnly: -FormWindow- procedure (window: Window.Handle, item: ItemKey] 

RETURNS [readonly: boolean]; 
GetReadOnly: -SimpleTextEdit- procedure [f : Field] 

RETURNS [readonly: boolean]; 
GetReadOnly: -StarWindowShell- procedure [sws: Handle] returns [boolean]; 
GetRegularCommands: «5ta rW/ndo w5/7e//~ procedure [sws: Handle] 

returns [MenuOata.MenuHandle]; 
GetResults: -TIPX- procedure ( 

window: Window.Handle, resultsWanted: ResultsWanted 'nil] 

RETURNS [results: TIP.Resultsj; 
GetScroilData: -StarWindowShell- PROCEDURE [sws: Handle] 

RETURNS [scrollData: ScrollData] 
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GetSeiection: -ContainerW/ndow- procedure (window: Window. Handle] 

RETURNS [ 

first: ContainerSource. Item Index, lastPlusOne: ContainerSource. Item Index]; 
GetSheilFromReference: -StarDesktop- procedure [ref: NSFiie. Reference] 

RETURNS [sws: StafWindowShell. Handle]; 
GetShowKeyboardProc: -KeyboardKey- procedure returns [ShowKeyboardProc]; 
GetSibling: -Window^ procedure [Handle] returns [Handle]; 
GetSleeps: -StarWindowShell" procedure [sws: Handle] returns [boolean]; 
GetSource: -ContainerWindow- procedure [window: Window.Handle] 

returns [source: ContainerSource. Handle]; 
GetState: -StarWindowShell- procedure [sws: Handle] returns [State]; 
GetStreakNature: -XChar- procedure (Character] returns [StreakNature]; 
GetStreakSuccession: -form W/ndow- procedure [ 

window: Window.Handle, item: ItemKey] returns (old: StreakSuccession]; 
GetStreakSuccession: -SimpleTextEdit- procedure (f: Field] 

RETURNS [SimpieTextOisplay.StreakSuccession]; 
GetString: -AtomicProfile- procedure [atom: Atom.ATOM] 

RETURNS [XString. Reader]; 
GetStringVaiue: -OptionFile- procedure [ 

section: XString.^Reader, entry: XString. Reader, 

call Back: procedure [value: XString. Reader], index: cardinal '0, 

file: NSFiie. Reference "xxxj; 
GetTable: -TIP- procedure [window: Window.Handle] returns [Table]; 
GetTable: -TIPStar- procedure [Placeholder] returns [TIP.Table]; 
GetTableLink: -TIP- procedure [from: Table] returns [to: Table]; 
GetTableOpacity: -TIP- procedure [table: Table] returns [boolean]; 
GetTabStops: -formWindow- procedure [window: Window.Handle] 

RETURNS (tabStops: TabStops]; 
GetTag: -FormWindow- procedure [window: Window.Handle, item: ItemKey] 

RETURNS [tag: XString. ReaderBody]; 
GetTextltemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, zone: uncounted zone] 

returns [value: XString. ReaderBody]; 
GetTransitionProc: -StarWindowShefl- procedure [sws: Handle] 

returns [Transit! onProc]; 
Getlype: -StarW/ndowS/ie//- procedure [sws: Handle] returns [ShellType]; 
GetUseBadPhosphor: -Window-- procedure [Handle] returns [boolean]; 
GetUserProflle: -OptionFile- procedure returns [file: NSFiie. Reference]; 
GetValue: -S/mp/e7"extfd/t- procedure [f: Field] returns [XString.ReaderBody]; 
GetVisibility: -FormWindow- procedure [window: Window.Handle, item: ItemKey] 

returns [visibility: Visibility]; 
GetWindow: -SimpleTextEdit- procedure [fc: FieldContext] 

RETURNS [window: Window.Handle]; 
GetWindow: -StarOeslctop- procedure returns [Window.Handle]; 
GetWindowitemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey] returns [value: Window.Handle]; 
GetWorkstationProf lie: -OptionFile- procedure 

RETURNS [file: NSFiie. Reference]; 
GetZone: "FormWindow- procedure [window: Window.Handle] 

RETURNS [zone: uncounted zone]; 
GetZone: -SimpleTextEdit- procedure [fc: FieldContext] 

RETURNS [uncounted ZONE]; 

GetZone: -StarWindowShell- procedure (sws: Handle] returns [uncounted zone]; 
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GlobalChangeProc: -FormWindow- type = procedure ( 

window: Window. Handle, item: ItemKey, calledBecauseOf: ChangeReason, 

clientOata: long pointer]; 
Gravity: -Window- type = {nil, nw, n, ne, e, se, s, sw, w, c, xxx}; 
Gray: -Display- procedure [ 

window: Handle, box: Window.Box, gray: Brick "fifty Percent, 

dstFunc: DstFunc "null, bounds: Window. BoxHandle *nil]; 
GrayTrapezoid: -Display- procedure [ 

window: Handle, t: Trapezoid, gray: Brick "fiftyPercent, 

dstFunc: DstFunc "null, bounds: Window.BoxHandle *imil]; 
Greater: -XLReai- procedure [a: Number, b: Number] returns [boolean]; 
GreaterEq: -XLReai- procedure [a: Number, b: Number] returns [boolean]; 
GreeterProc: "IdleControl- type = procedure returns [Atom.ATOM]; 
Half: -XLReai- procedure [Number] returns [Number]; 
Handle: -ContainerCache- type = long pointer to Object; 
Handle: -ContainerSource- type = long pointer to Procedures; 
Handle: -Cursor- type = long pointer to Object; 
Handle: -O/sp/ay- TYPE = Window.Handle; 
Handle: ~StafW/ndowS/»e//- type = record [Window.Handle]; 
Handle: -Wir^dow- type = long pointer to Object; 
Handle: -Xformat- TYPE = long pointer to Object; 
Handle: -XMessage- type = long pointer to Object; 
Handle: -XToken- type = long pointer to Object; 

HasAnyBeenChanged: -FormWindow- procedure [window: Window.Handle] 

returns [yes: boolean]; 
HasBeenChanged: -Form W/ndow- procedure [window: Window.Handle, item: ItemKey] 

RETURNS [yes: boolean]; 
HaveOispiayedParasite: -StarWindowShell- procedure [sws: Handle] 

RETURNS [boolean]; 

Hex: -XFormat- procedure [h: Handle "nil, n: long cardinal]; 
HexFormat: -XFormat— NumberFormat; 
HighlightThisKey: -SoftKeys- procedure [ 

window: Window.Handle, key: cardinal "nullKey]; 
HostNumber: -XFormat- procedure [ 

h: Handle "nil, hostNumber: System. HostNumber, format: NetFormat]; 
HowHard: -Selection- procedure [target: Target, enumeration: boolean "false] 

returns [difficulty: Difficulty]; 
IconColumn: -FileContainerSource- procedure 

returns [attribute ColumnContentslnfo]; 
Idle: -IdleControl- procedure; 

ignoreType: -Containee- NSFile.Type = 37777777777B; 
Implementation: -Conta/nee-- TYPE = record [ 

implementors: long pointer 'nil, 

name: XString.ReaderBody "xxx, 

small Pi ctureProc: SmallPictureProc "nil, 

pictureProc: PictureProc "nil, 

convertProc: Selection. ConvertProc "nil, 

genericProc: GenericProc "nil]; 
Implementation: -Ondo- TYPE = record [ 

opportunity: Proc, 

roadblock: procedure [XString. Reader], 
doAnUndo: procedure, 
doAnUnundo: procedure, 
deleteAII: procedure]; 
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IndexFromMark: -ContainerCache- procedure [mark: Mark] 

RETURNS [index: cardinal]; 
Info: -Cursor- TYPE » record [type: Type, hotX: [0..15], hotY: [0..15]]; 
Info: -F/7eConta/ner5ource- procedure [source: ContainerSource.Handle] 

RETURNS [ 

file: NSFile. Reference, columns: ColumnContents, scope: NSFile.Scope, 
options: Options); 
Info: -Soff/Ceys- procedure [window: Window. Handle] 

RETURNS [ 

table: TIP.Table, notifyProc: TIP.NotifyProc, labels: Labels, 
highlightedKey: cardinal, outlinedKey: cardinal]; 
InitBreakTable: -XString- procedure ( 

r: Reader, stopOrNot: StopOrNot, otherSets: StopOrNot] 

RETURNS [break: BreakTableObject]; 
Initialize: -Wmdow- procedure [ 

window: Handle, display: DisplayProc, box: Box, parent: Handle 'rootWindow, 

sibling: Handle *nil, child: Handle "nil, clearing Required: boolean "true, 

windowPane: boolean "false, under: boolean "false, cookie: boolean "false, 

color: BOOLEAN "false]; 
InitiaiizeWindow: -Window- procedure [ 

window: Handle, display: DisplayProc, box: Box, parent: Handle "rootWindow, 

sibling: Handle "nil, child: Handle "nil, ciearingRequired: boolean "true, 

windowPane: boolean "false, under: boolean "false, cookie: boolean "false, 

color: boolean "false]; 
InsertlntoTree: -Window- procedure [window: Handle]; 
Insertltem: -ContainerCache- procedure [ 

cache: Handle, before: cardinal, addData: AddOata] 

RETURNS [handle: ItemHandlej; 
insertltem: -FormWindow- procedure [ 

window: Window.Handie, item: ItemKey, line: Line, beforeltem: ItemKey, 

preMargin: cardinal "0,tabStop: cardinal "nextTabStop, 

repaint: boolean "true]; 
InsertLine: -FormWindow- procedure [ 

window: Window.Handie, before: Line, spaceAboveLine: cardinal *0] 

RETURNS [line: Line); 

InstailBody: -StarWindowShell- procedure [sws: Handle, body: Window.Handie]; 

InstallFormWindow: -PropertySheet- procedure [ 

shell: StarWindowShell. Handle, menultemProc: MenultemProc, 

menuitems: Menultems "propertySheetDefaultMenu, title: XString. Reader "nil, 

formWindow: Window.Handie, afterTakenDownProc: MenultemProc "nil]; 

InsufficientRoom: -XString- signal [ 

needsMoreRoom: Writer, amountNeeded: cardinal]; 

IntegerPart: -XLReal- procedure [Number] returns [Number]; 

Interpolator: -Disp/ay- TYPE = record [val: FixdPtNum,dVal: FixdPtNumj; 

IntersectBoxes: -Window- procedure [b1 : Box, b2: Box] returns [box: Box]; 

Invalid: -Xr/me- error; 

InvalidateBox: -Window- procedure [ 

window: Handle, box: Box, clarity: Clarity "isDirty]; 

InvalidateCache: -Conta/nee- procedure [data: DataHandle]; 

InvalidateWholeCache: -Containee- procedure; 

InvalidEncoding: -XString- error [ 

invalidReader: Reader, firstBadByteOffset: cardinal]; 

InvalidHandle: -BlackKeys- error; 

InvalidHandte: -SoftKeys- error; 

InvalidNumber: -XString— signal; 

InvaiidTabie: -f/P- signal [type: TableError, message: XString. Reader]; 
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Invert: -Cursor- procedure returns [boolean]; 
Invert: -Display- procedure [ 

window: Handle, box: Window.Box, bounds: Window.BoxHandle 'nil]; 
IsBitmapUnderVariant: -Window- procedure [Handle] returns [boolean]; 
IsBodyWindowOutOflnterior: -5tdrt/1^/ndow5/ie//~ procedure [body: Window.Handle] 

RETURNS [boolean]; 

IsCloseLegal: --StarW/ndowSAje//-- procedure [ 

sws: Handle, doseAII: boolean 'false] returns [boolean]; 
IsCloseLegal Proc: -StarW/ndowS/ie//- type = procedure [ 

sws: Handle, closeAII: boolean 'false] returns [boolean]; 
IsCloseLegalProcReturnsFalse: -StarWindowSheU- IsCloseLegal Proc ; 
IsCoiorVarlant: -Window- procedure [Handle] returns [boolean]; 
IsCookleVariant: -Window- procedure [Handle] returns [boolean]; 
IsOescendantOfRoot: -Window- procedure [Handle] returns [boolean]; 
Isit: -ContainerWindow- procedure [window: Window.Handle] 

RETURNS [yes: boolean]; 
Isit: -Fi/eContd/ner5ource~ PROCEDURE [source: ContainerSource.Handle] 

RETURNS [boolean]; 

Isit: -formW/ndow- PROCEDURE [window: Window.Handle] returns [yes: boolean]; 
Isit: -MessageWindow- procedure [Window.Handle] returns [yes: boolean]; 
IsPlaceinBox: -Window- procedure [place: Place, box: Box] returns [boolean]; 
IsSpecial: -XLReal- procedure [Number] 

RETURNS [yes: boolean, index: Speciailndex]; 
Item: -MenirData- TYPE = Privateltem; 

Item: -xro^fen- procedure [h: Handle, temporary: boolean 'true] 

RETURNS [value: XString.ReaderBody]; 
ItemClients: -ContaineKache- procedure [item: Item Handle] 

RETURNS [clientData: long pointer]; 
ItemClientsLength: -ContainerCache- procedure [handle: ItemHandle] 

RETURNS [dataLength: cardinal]; 
ItemOata: -MenuData- procedure [item: ItemHandle] returns [long unspecified]; 
ItemGeneric: -ContainerSource- ItemGenericProc; 
ItemGenericProc: -ContainerSource- type » procedure [ 

source: Handle, itemlndex: Itemlndex, atom: Atom.ATOM, 

changeProc: ChangeProc 'nil, changeProcData: long pointer 'nil] 

returns [long unspecified]; 
ItemHandle: -Conta/nerCac/ie- TYPE = long pointer to ItemObject; 
ItemHandle: -/WenuData- type = long pointer to Item; 
Itemlndex: -Conta/nerCac/ie-- procedure [Item: ItemHandle] 

RETURNS [index: cardinal]; 
Itemlndex: -ContainerSource- type = cardinal; 
Item Key: -form W/ndow- type = cardinal; 
ItemName: -/WenuData- procedure [item: ItemHandle] 

RETURNS [name: XString.ReaderBody]; 
ItemNameWidth: -/WenuData-- procedure [item: ItemHandle] returns [cardinal]; 
ItemNthString: -ContainerCache- procedure [item: ItemHandle, n: cardinal] 

returns [XString.ReaderBody]; 
ItemObject: -Containe<ache~ type; 

ItemProc: -MenuData- procedure [item: ItemHandle] returns [proc: MenuProc]; 
ItemStringCount: -Conta/nerCac/)e- procedure [Item: ItemHandle] 

RETURNS [strings: cardinal]; 
ItemType: -FormWindow- type = machine dependent{ 

choice, multiplechoice, decimal, integer, boolean, text, command, tagonly, 

window, last(1S)}; 
JoinDirection: -XChar- TYPE = {nextCharToRight, nextCharToLeft}; 
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KeyBits: -leve//Vffeys~ type s packed array Key Name of DownUp; 
KeyBits: -HP- type « Level IVKeys. KeyBits; 

Keyboard: -S/ac/c/Ceys- type s long pointer to KeyboardObject *nil; 

KeyboardClass: "KeyboardKey— typb s {system, client, special, all, none}; 

KeyboardObject: -S/ac/f/Ceys- type » record [ 
table: TIP.Table "nil, 
charTranslator: TIP.CharTranslator "xxx, 
pictureProc: PictureProc "nil, 
label: XString.ReaderBody "xxx, 
clientData: long pointer "nil]; 

KeyName: -LevellVKeys- type = machine dependentC 

notAKey, Key$et1(8), Keyset2, Keysets, Keyset4, Keysets, MouseLeft, 
MouseRight, MouseMiddle, Five, Four, Six, E, Seven, D, U, V, Zero, K, Minus, 
P, Slash, Font, Same, BS, Three, Two, W, Q, S, A, Nine, I, X, O, L, Comma, 
CloseQuote, RightBracket, Open, Keyboard, One, Tab, Para Tab, F, Props, C, J, 
B, Z, LeftShift, Period, SemiColon, NewPara, OpenQuote, Delete, Next, R, T, G, 
Y, H, Eight, N, M, Lock, Space, LeftBracket, Equal, RightShift, Stop, Move, 
Undo, Margins, R9, L10, L7, L4, LI, A9, RIO, A8, Copy, Find, Again, Help, 
Expand, R4, 02, 01, Center, T1, Bold, Italics, Underline, Superscript, 
Subscript, Smaller, T10, R3, Key47,A10, Defaults, All, A 12}; 

KeyName: -r/P- TYPE a Level IVKeys. KeyName; 

Keys: -XComSoftMessage- type « machine dependent{ 
time, date, dateAndTime, am, pm, january, february, march, april, may, june, 
july, august, September, October, november, december, monday, tuesday, 
Wednesday, thursday, friday, Saturday, Sunday, decimalSeparator, 
thousandsSeparator}; 

Keystations: -KeyboardWindow- type = machine oependent{ 

k1, k2, k3, k4, kS, k6, k7, kS, k9, klO, k1 1, k12, k13, kl4, k1 5, k16, k17, 
k18, k19, k20, k21, k22, k23, k24, k25, k26, k27, k28, k29, k30, k31 , k32, 
k33, k34, k35, k36, k37, k38, k39, k40, k41, k42, k43, k44, k45, k46, k47, 
k48, a1, a2, a3, a4, aS, a6, a7, a8, a9. alO, a1 1, a12, last(96)}; 

KeyToCharProc: "TIP- type = procedure [ 

keys: long pointer to KeyBits, key: KeyName, downUp: OownUp, 
data: long pointer, buffer: XString. Writer]; 

Label Record : -Soft/Ceys- TYPE a record [ 

unshifted: XString.ReaderBody "xxx, shifted: XString.ReaderBody "xxxj; 

Labels: -SoftKeys- type = long descriptor for array cardinal of Label Record; 

lasstOldApplkationSpecific: -BWSAttributeTypeS" 
NSFite. Extended AttributeType = 10457B; 

lastBWSType: -ewSAtfr/6ote Types- NSFile.ExtendedAttributeType = 10777B; 

LayoutError: -Form Window- signal [code: LayoutErrorCode]; 

LayoutErrorCode: -FormWindow- type = {onTopOfAnotherltem, 

notEnufTabsDefined}; 

LayoutlnfoFromltem: -FormWindow- procedure [ 
window: Window.Handle,jtem: ItemKey] 

returns [line: Line, margin: cardinal, tabStop: cardinal, box: Window.Box]; 
LayoutProc: -Form W/ndow- type = procedure [ 

window: Window.Handle, clientOata: long pointer]; 
Less: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
LessEq: -XLReal- procedure [a: Number, b: Number] returns [boolean]; 
LimitProc: -StarWindowShell- type = procedure [sws: Handle, box: Window.Box] 

RETURNS [Window.Box]; 
Line: -Display- procedure [ 

window: Handle, start: Window.Place, stop: Window.Place, 

lineStyle: LiheStyle "nil, bounds: Window.BoxHandle "aiil]; 
Line: -Form Window- type [2]; 



D-27 



D 



Listing of Public Symbols 



Line: -XFormat- procedure [ 

h: Handle 'nil, r: XStrlng. Reader, n: cardinal "1]; 
Line: -XToken- FilterProcType; 

LineStyle: -D/sp/ay- TYPE a long pointer to LineStyleObject; 
Li neSty I eObj ect: ~0/sp/ay- TYPE = record [ 

widths: array [0..5] of cardinal, thicicness: cardinal]; 
LinelipBoxes: -FormWindow- procedure [ 

window: Window.Handle, 

items: long descriptor for array cardinal of Item Key "xxx]; 
In: -XLReal" procedure (Number] returns [Number]; 
Log: -XLReal- procedure (base: Number, arg: Number] returns [Number]; 
logoff: -StarDesktop- Atom.ATOM; 
logon: -StarOes/ftop- Atom.ATOM; 

LogonSesslon: -BWSZone- procedure returns [uncounted zone]; 
logonSession: -BWSZone- uncounted zone; 
LookAtTextitemValue: -FormWindow- procedure ( 

window: Window.Handle, item: ItemKey] returns [value: XString.ReaderBody]; 
Lop: -XString- procedure [r: Reader] returns [c: Character]; 
Losing FocusProc: -HP-type = procedure [ 

w: Window.Handle, data: long pointer]; 
Lowercase: -XChar- procedure [c: Character] returns [Character]; 
LTP: -XTime- type = RECORD [ 

r: select t: * from 

useSystem a > null, useThese = > [Itp: System. LocalTimeParameters], endcase); 
mailStatus: -SWSAttr/bute fypes- NSFile.ExtendedAttributeType = 1041 1B; 
Make: -Atom- procedure [pName: XString. Reader] returns [atom: atom]; 
Make: -XC/iar- procedure [set: Environment. Byte, code: Environment. Byte] 

returns [Character]; 
Make: -XCharSetO- procedure [code: CodesO] returns [XChar. Character]; 
Make: ~XCharSet7W- procedure [code: Codes164] returns (XChar. Character]; 
Make: ~XCharSet356-- procedure (code: Codes356] returns [XChar.Character]; 
Make: -XC/»afSet357- procedure [code: Codes357] returns (XChar.Character]; 
Make: '-XCharSetSSO- procedure [code: Codes360] returns [XChar.Character]; 
Make: -XCharSet361-- procedure [code: Codes361] returns [XChar.Character]; 
Make: ~XC/)arSet4t- procedure [code: Codes41] returns [XChar.Character]; 
Make: -XCharSet42- procedure [code: Codes42] returns [XChar.Character]; 
Make: ~XCharSet43- procedure [code: Codes43] returns [XChar.Character]; 
Make: ~XC/7arSet44- procedure [code: Codes44] returns [XChar.Character]; 
Make: -XCharSetAS- procedure (code: Codes45] returns [XChar.Character]; 
Make: -XCharSetAS- procedure [code: Codes46] returns [XChar.Character]; 
Make: -XC/iafSet47- procedure [code: Codes47] returns (XChar.Character]; 
MakeAtom: -Atom" procedure [pName: long string] returns (atom: atom]; 
MakeBooleanltem: -form W/ndow- procedure [ 

window: Window.Handle, myKey:. ItemKey, tag: XString. Reader 'nil, 

suffix: XString. Reader 'nil, visibility: Visibility 'visible, 

boxed: boolean 'true, readonly: boolean 'false, 

changeProc: BooleanChangeProc 'nil, label: BooleanltemLabel, 

initBoolean: boolean 'true]; 
MakeChoiceitem: -Form Window- procedure [ 

window: Window.Handle, myKey: ItemKey, tag: XString. Reader 'nil, 

suffix: XString. Reader "nil, visibility: Visibility 'visible, 

boxed: boolean "true, readonly: boolean 'false, values: Choiceltems, 

initCholce: Choicelndex, fullyDisplayed: boolean 'true, 

verticallyDisplayed: boolean 'false, hintsProc: Choice HintsProc 'nil, 

changeProc: ChoiceChangeProc 'nil, 

outlineOrHighlight: OutlineOrHighlight "highlight]; 
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MakeCommandltem: -FormWindow- procedure ( 

window: Window. Handle, myKey: ItemKey, tag; XString. Reader 'nil, 
suffix: XString. Reader "nil, visibility: Visibility "visible, 

boxed: boolean "true, readonly: boolean "false, commandProc: CommandProc, 
command Name: XString. Reader, clientData: long pointer "nil]; 

MakeOecimalitem: -FormWindow- procedure [ 

window: WIndow.Handle, myKey: ItemKey, tag: XString.Reader "nil, 

suffix: XString.Reader "nil, visibility: Visibility "visible, 

boxed: boolean "true, readonly: boolean "false, signed: boolean "false, 

width: cardinal, InitDecimal: XLReal. Number "xxx, 

wrapUnderTag: boolean "false, hintsProc: TextHintsProc "nil, 

nextOutOfProc: NextOutOfProc "nil, displayTemplate: XString.Reader "nil, 

SPECIALKeyboard: BlackKeys. Keyboard "nil]; 

Makeintegeritem: -FormWindow- procedure [ 

window: WIndow.Handle, myKey: ItemKey, tag: XString.Reader "nil, 
suffix: XString.Reader "nil, visibility: Visibility "visible, 
boxed: boolean "true, readonly: boolean "false, signed: boolean "false, 
width: cardinal, initlnteger: long integer "0, wrapUnderTag: boolean "false, 
hintsProc: TextHintsProc "niL; nextOutOfProc: NextOutOfProc "nil, 
SPECIALKeyboard: BlackKeys. Keyboard "nil]; 

MakeltemsProc: -FormWindow- type s procedure [ 
window: WIndow.Handle, clientData: long pointer]; 

MakeMenultem: -FormWindow- procedure [ 

window: WIndow.Handle, myKey: ItemKey, tag: XString.Reader nil, 
suffix: XString.Reader "nil, visibility: Visibility "visible, 
boxed: boolean "true, menu: MenuData.MenuHandle]; 

MakeMultipleChoiceltem: -FormWindow- procedure [ 

window: WIndow.Handle, myKey: ItemKey, tag: XString.Reader "nil, 
suffix: XString.Reader "nil, visibility: Visibility "visible, 
boxed: boolean "true, readonly: boolean "false, values: Choiceltems, 
inltCholce: long descriptor for array cardinal of Choicelndex, 
fullyDisplayed: boolean "true, vertlcallyDisplayed: boolean "false, 
hintsProc: ChoiceHintsProc "nil, changeProc: MultipleChoiceChangeProc "nil, 
outlineOrHighlight: OutlineOrHighllght "highlight]; 

MakeNegative: -Cursor- procedure; 

MakePositlve: -Cursor- procedure; 

MakeSpecial: -XLReal- procedure [index: Specialindex] returns [Number]; 

MakeTagOnlyltem: -FormWindow- procedure [ 

window: WIndow.Handle, myKey: ItemKey, tag: XString.Reader, 
visibility: Visibility "visible]; 

MakeTextltem: -FormWindow- procedure [ 

window: WIndow.Handle, myKey: ItemKey, tag: XString.Reader "nil, 

suffix: XString.Reader "nil, visibility: Visibility "visible, 

boxed: boolean 'true, readonly: boolean 'false, width: cardinal, 

inltString: XString.Reader "nil, wrapUnderTag- boolean "false, 

password Feed back: boolean "false, hintsProc: TextHintsProc "nil, 

nextOutOfProc: NextOutOfProc "nil, 

SPECIALKeyboard: BlackKeys. Keyboard "nil]; 

MakeWindowltem: -FormWindow- procedure [ 

window: Window. Handle, myKey: ItemKey, tag: XString.Reader "nil, 
visibility: Visibility "visible, boxed: boolean "true, size: WIndow.Dlms, 
nextlntoProc: NextlntoProc "nil] returns [cllentWindow: WIndow.Handle]; 

Manager: -TIP- type = record [ 

table: Table, window: WIndow.Handle, notify: NotlfyProc]; 

ManagerData: "Se/ect/on-TYPE = long pointer; 
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Map: -XString- procedure (r: Reader, proc: MapCharProc] 

RETURNS [c: Character]; 
MapAtomProc: -Atom- TYPE = procedure [atom] returns [boolean]; 
MapAtoms: -Atom- procedure [proc: MapAtomProc] returns [lastAtom: atom]; 
MapCharProc: -XString- type = procedure [c: Character] 

returns [stop: boolean]; 
MappedDefaultFont: -SimpleTextFont- procedure returns [Mapped FontHandle]; 
MappedFont: -S/mp/efextFont- procedure [name: XString. Reader *nil] 

returns [MappedFontHandle]; 
Mapped FontDescriptor: -SimpieTextFont- type; 
MappedFontHandle: -SimpleTextFont" type = long pointer to 

MappedFontOescriptor; 
MapPList: -Atom- procedure [atom: atom, proc: MapPListProc] 

returns [lastPair: RefPair]; 
MapPListProc: -Atom- type = procedure [RefPair] returns [boolean]; 
Mark: -ContainerCache- type = long pointer to MarkObject; 
MarkObject: -ContainerCache- type; 

Match: -Selection- procedure [pointer: ManagerOata] returns [match: boolean]; 
maxStringLength: -Se/ect/on~ cardinal = 200; 
MaybeQuoted: -XToken- procedure [ 

h: Handle, data: FilterState, filter: FilterProcType 'NonWhiteSpace, 

isQuote: QuoteProcType "Quote, skip: SkipMode "whiteSpace, 

temporary: boolean 'true] returns [value: XString.ReaderBody]; 
MeasureString: -SimpleTextDisplay- procedure [ 

string: XString. Reader, lineWidth: cardinal *177777B, 

wordBreak: boolean "true, streakSuccession: StreakSuccession "fromFlrstChar, 

font: SimpleTextFontMappedFontHandle "nil] 

RETURNS (width: cardinal, result: Result, rest: XString.ReaderBody]; 
MenuArray: -MenuData- procedure [menu: Menu Handle] 

RETURNS [array: ArrayHandlej; 
MenuEnumProc: StarWindowShell- type = procedure [menu: MenuOata.MenuHandle] 

RETURNS [stop: BOOLEAN "FALSE]; 

MenuHandle: -/VfenuOata- TYPE = long pointer to MenuObject; 
MenultemProc: -PropertySheet- type = procedure [ 

shell: StarWindowShel I. Handle, formWindow: Window.Handle, 

menultem: MenultemType, clientData: long pointer] returns [ok: boolean]; 
Menu Items: -PropertySAieet- TYPE = packed array MenultemType of 

BooleanFalseOefault; 
MenultemType: -Prope/tyS/)eet- type = { 

done, apply, cancel, defaults, start, reset}; 
MenuObject: -MenuData- type a PrivateMenu; 
MenuProc: -MenuData- type = procedure [ 

window: Window.Handle, menu: MenuHandle, itemOata: long unspecified]; 
MenuTltle: -MenuData- procedure [menu: MenuHandle] 

RETURNS [title: Item Handle]; 
Messages: -XMessage- type = long descriptor for array cardinal of Msg Entry; 
MessagesFromFlle: -XMessage- procedure [ 

fileName: long string, clientData: ClientData, proc:- DestroyMsgsProc] 

RETURNS [msg Domains: Msg Domains]; 
MessagesFrom Reference: -XMessage- procedure [ 

file: NSFile. Reference, clientData: ClientData, proc: DestroyMsgsProc] 

RETURNS [msgDomains: MsgDomains]; 
MinDimsChangeProc: -FormWindow- type = procedure [ 

window: Window.Handle, old: Window.Dims, new: Window.Dims]; 
MinusLandBitmapUnder: -Window- type [6]; 
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MinusLandColor: -Window- ttpe [1]; 

Mi nusLandCookieCutter: -Window-- TYPE (21; 

Mode: -TIPStar-TYPB a {normal, copy, move, sameAs); 

ModeChangeProc: -TVPStar- TYPE = procedure [ 

old: Mode, new: Mode, ciientOata: long pointer]; 
ModlfySource:^ -Conta/nerW/ndow-- procedure ( 

window: Window. Handle, proc: SourceModifyProc]; 
Months: -XComSoftMessage- type « Keys (]anuary..decemberl; 
MoreFlavor: -StarWindowShell- type = {before, after}; 
MoreScrol I Proc: -Star W/ndowS/)e//~ type = procedure [ 

sws: Handle, vertical: boolean, flavor: MoreFlavor, amount: cardinal]; 
MouseTransformerProc: -Window- type = procedure [Handle, Place] 

returns [Handle, Place]; 
Move: -Selection- procedure (v: ValueHandle, data: long pointer]; 
MoveintoWindow: -Cursor- procedure [ 

window: Window.Handle, place: Window.Place]; 
MoveMark: -ContainerCache- procedure [mark: Mark, newlndex: cardinal]; 
MsgDomain: -XA<fessage-TYPE = record [ 

applicationName: XString.ReaderBody, handle: Handle]; 
MsgOomains: -X/Wessage- type = long descriptor for array cardinal of MsgDomain; 
MsgEntry: -XMessage- type s record [ 

msgKey: MsgKey, 

msg: XString.ReaderBody, 

translationNote: long string "nil, 

translatable: boolean "true, 

type: MsgType "userMsg, 

id: MsglD]; 

"^i^ MsglD: -XMessage- type = cardinal; 

MsgKey: -XMessage- type = cardinal; 

MsgKeyList: -XA/fessage-- type = long descriptor for array cardinal of MsgKey; 

MsgType: -XMessage- type = { 

userMsg, template, argList, menultem, pSheetltem, commandltem, errorMsg, 
infoMsg, promptltem, windowMenuCommand, others}; 

MultiAttributeFormatProc: -F/'/eConta/nerSoorce-- TYPE = procedure [ 
containeeimpi: Containee.lmplementation, containeeOata: Containee.DataHandle, 
attrRecord: NSFile.Attributes, displayString: XString. Writer]; 

MultipleChoiceChangeProc: -FormW/ndoiv-- TYPE = procedure [ 
window: Window.Handle, item: Item Key, calledBecauseOf : ChangeReason, 
oldValue: long descriptor for array cardinal of Choicelndex, 
newValue: long descriptor for array cardinal of Choicelndex]; 

Multiply: -XLReal- procedure [a: Number, b: Number] returns [Number]; 

NameAndVersionColumn: -FileContainerSourceExtra- procedure 

RETu RNS [m u I ti pi eAttri butes Fi I eConta i nerSou rce. Col u m nConten ts I n f o] ; 

NameColumn: -FileContainerSource- procedure 
RETURNS [attribute ColumnContentslnfo]; 

NeededDims: -/^ormW/ndow- procedure (window: Window.Handle] 
RETURNS [Window. Dims]; 

Negative: -XLReal- procedure [Number] returns [Number]; 

netAddr: -SWSAttr/buterypes- NSFile.ExtendedAttributeType = 104028; 

NetFormat: -XFormat- type s {octal, hex, productSoftware}; 

NetworkAddress: -XFormat- procedure [ 

h: Handle "nil, networkAddress: System. NetworkAddress, format: NetFormat]; 

networkName: -SWSAttr/buterypes- NSFile.ExtendedAttributeType = 10404B; 

NetworkNumber: -XFormat- procedure ( 

h: Handle "nil, networkNumber: System, NetworkNumber, format: NetFormat]; 
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New: "WindoW" procedure [ 

under: boolean ~false, cookie: boolean 'false, color: boolean "false, 

zone: uncounted zone 'LOOPHOLEIOJ] returns (Handle]; 
newlcon: StarDesktop" Atom. atom; 

NewResoiveBuffer: -SimpleTextDisplay- procedure [words: cardinal] 

returns [ResolveBufferj; 
NewStandardCloseEverything: StarWindowShellExtra" procedure 

RETURNS [ 

numberLeftOpen: cardinal "0, 

lastNotClosed: StarWIndowShell. Handle UOOPHOLE(0]]; 
NewWriterBody: -XString- procedure [maxLength: cardinal, z: uncounted zone] 

RETURNS (WriterBodyl; 
NextlntoProc: -A^ormW/ndow-TYPE = procedure [ 

window: Window.Handle, item: ItemKey]; 
NextOutOfProc: -form W/ndoiv-- type = procedure [ 

window: Window.Handle, item: ItemKey]; 
nextPlace : -StarDesktop- Wi ndow. Place; 
nextTabStop: -Form IV/ndow- CARDINAL = 177777B; 
NiiData: -XToken- signal; 
nonQuote: -XToken- XChar.Character = 0; 
NonWhiteSpace: -Xfoilfen- FilterProcType; 
NopDestroyProc: -Context- DestroyProcType; 
NopFree: -Selection- ValueFreeProc; 

nopFreeValueProcs: -Selection- readonly long pointer to ValueProcs; 

NormalTable: -TiPStar- procedure returns [TIP. Table]; 

noScrol I Data : -StarWindowShell- Scrol I Data; 

NoSuchAtom: -Atom- error; 

NoSuchOependency: -Event- error; 

not: -XChar- Character = 177777B; 

noTabStop: -FormlV/ndow- cardinal a 177776B; 

NotAProf ileFile: -OptionFile- signal; 

NotEq: -XLReal- procedure (a: Number, b: Number] returns [boolean]; 
Notes: -XTime- type = { 

normal, nozone, zonedGuessed, noTime, timeAndZoneGuessed}; 
Notify: -Event- procedure [event: EventType, eventData: long pointer "nil] 

RETURNS [veto: boolean]; 
NotifyProc: -T/P-type = procedure [window: Window.Handle, results: Results]; 
NSChar: -XFormat- procedure [h: Handle "nil, char: NSString.Character]; 
NSLine: -XFormat- procedure [ 

h: Handle "nil, s: NSString.String, n: cardinal "1]; 
NSString: -XFormat- procedure (h: Handle "nil, s: NSString. String]; 
NSStringFromReader: -XString- procedure [r: Reader, z: uncounted zone] 

RETURNS [ns: NSString.String]; 
NSStringObject: -XFormat- procedure (s: long pointer to NSString.String] 

RETURNS [Object]; 
SStringProc: -XFormat- FormatProc; 
NthCharacter: -XString- procedure [r: Reader, n: cardinal] 

RETURNS [c: Character]; 
null: -Atom- atom; 
null: ~XC/iar~ Character = 0; 
nullBox: -Window- Box; 
null Data: -Containee- Data; 
null Handle: -StarWindowShell- Handle; 
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null Item : -Conta/nerSource-- Itemlndex = 177777B; 
null ItemKey: -Form Window- ItemKey = 177777B; 
nul I Key : -SoftAfeys- CARDINAL = 177777B; 
nullManager: -TIP- Manager; 
nullOption: -ProductFactoring- Option; 
nullPeriodicNotlfy: -TIP- PeriodicNotify; 
nullPicture: -BlackKeys- bitmap Picture; 
nullPlace: -PropertySheet- Window. Place; 
nullPrerequisite: -ProductFactoring- Prerequisite; 
nullReaderSody: -XString- ReaderBody; 
nullVaiue: -Se/ect/on~ Value; 
nullWriterBody: -XString- WriterBody; 
Number: -XFormat- procedure [ 

h: Handle "nil, n: long unspecified, format: NumberFormat]; 
Number: -XLReal- type [4]; 
Number: -XToken- procedure [ 

h: Handle, radix: cardinal, signalOnEr-or: boolean 'true] 

RETURNS (u: long UNSPECIFIED]; 

NumberFormat: -XFormat- type = re :ord [ 
base: [2..36] M2, 
zerofill: boolean 'FALSE, 
signed: boolean "false, 
columns: [0..255] *0]; 

NumberOf items: -FormWindow- prciedure (window: Window.Handle] 

RETURNS (cardinal); 

numberOf Keys: -SoftKeys- cardinal = 8; 

NumberToPair: -XLReal- procedure [r: Number, digits: [1.13]] 

returns (negative: boolean, exp: integer, mantissa: Digits]; 

Numeric: -XToken- FilterProcType; 

Object: -ContainerCache- type; 

Object: -Cursor- type = record (info: Info, array: UserTerminal.CursorArrayJ; 
Object: -Window- type [19]; 
Object: -XFormat- type = record ( 
proc: FormatProc, 

context: XString.Context "LOOPHOLE[0], 
data: CiientOata "nil]; 
Objea: -XMessage- type; 

Object: -XToken- type s machine dependent record [ 
getChar(0:0..31): GetCharProcType, break(2:0..15): XChar. Character "0]; 
ObscuredBySibling: -W/ndow- procedure (Handle] returns [boolean]; 
Octal: -XFormat- procedure (h: Handle "nil, n: long unspecified]; 
Octal: -XToken- procedure (h: Handle, signalOnError: boolean "true] 

RETURNS [c: long CARDINAL); 

Octal Format: -XFormat— NumberFormat; 

oldDateSent: -BWSAttr/buterypes- NSFile.ExtendedAttributeType = 10413B; 
Open: -Catalog- procedure ( 

catalogType: NSFile.Type, session: NSFile.Session *LOOPHOLE[0]] 

returns (catalog: NSFile.Handle]; 
Opportunity: -Undo- Proc; 
Option: -ProductFactoring- ^ype = record ( 

product: Product, productOption: ProductOption]; 
Options: -FileContainerSource- ^vpe = record [readonly: boolean "false]; 
optionSheetDefaultMenu: --Prope/tyS/ieet- Menu Items; 

outbasketPSData: -8WS/Attr/buterypes- NSFile.ExtendedAttributeType = 10410B; 
OutlineOrHighlight: ~FormM//ndow~TYPE = {outline, highlight}; 
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OutlineThisKey: -SoftKeys- procedure [ 

window: Window.Handle, key: cardinal "nullKeyJ; 
Overflow: -XString-- signal; 

owner: -8WS>Attr/bute fypes- NSFile.ExtendedAttributeType = 10377B; 
Pack: -Xr/me- procedure [unpacked: Unpacked, useSystemLTP: boolean "true] 

RETURNS [time: System. GreenwichMeanTlme]; 
Packed: -xr/me- TYPE = System.GreenwichMeanTime; 
paintFlags: --Display- BitBltFlags; 
paintGray Flags: -Display- BitBltFlags; 
Pair: -Atom- type = record [prop: atom, value: RefAnyJ; 
PairToNumber: -XLReal- procedure [ 

negative: boolean, exp: integer, mantissa: Digits] RETURNS [n: Number]; 
Parallelogram: -Display- tvps = recopd[ 

x: Interpolator, y: integer, w: natur^., h: natural]; 
ParseChoiceltemMessage: -FormW/noow/WessageParse- procedure [ 

ciioiceltemMessage: XString. Reads'^ zone: uncounted zone] 

RETURNS [choiceltems: FormWindow Thoiceltems]; 
ParseReader: -XTime- procedure [ 

r: XString. Reader, treatNumbersAs: 'reatNumbersAs *dayMonthYear] 

RETURNS (time: System.GreenwichMeanTime, notes: Notes, length: cardinal]; 
ParseWith Template: -XTime- procedure [ 

r: XString. Reader, template: XString. Reader] 

RETURNS [time: System.GreenwichMeanTime, notes: Notes, length: cardinal]; 
PeekForFlushness: -SimpleTextDisplay- procedure [ 

requested Flushness: Flushness, string: XString. Reader] returns [Flushness]; 
PeekForStreakSuccession: -SimpleTextDisplay- procedure. [ 

requestedStreakSuccession: StreakSuccession, string: XString. Reader] 

returns [StreakSuccession]; 
PeriodicNotify: -TIP- type [IJ; 

Permanent: -BWSZone- procedure returns [uncounted zone]; 
permanent: -BWSZone- uncounted zone; 
PFonts: -ProductF acton ngProducts- Product a 4; 
Pi: -XLReal- procedure returns [Number]; 
Picture: -BlackKeys- type = record [ 

variant: select type: PictureType from 

bitmap = > [bitmap: long pointer], text = > [text: XString. Reader], endcas^]; 
PictureAction: -BlackKeys- type = {acquire, release}; 
PictureProc: -BlackKeys- type = procedure [ 

keyboard: Keyboard, action: PictureAction] 

returns [picture: Picture "nullPicture, geometry: Geometry Table *nil]; 
PictureProc: -Containee- type = procedure [ 

data: DataHandle, window: Window.Handle, box: Window.Box, old: PictureState, 

new: PictureState]; 
PictureReal: -XLReal- procedure [ 

h: XFormat. Handle "nil, r: Number, template: XString. Reader]; 
PictureState: -Containee- type = { 

garbage, normal, highlighted, ghost, reference, referenceHighiighted}; 
PictureType: -BlackKeys- type = {bitmap, text}; 

Piece: -XString- procedure [r: Reader, firstChar: cardinal, nChars: cardinal] 

RETURNS [piece: ReaderBody, endContext: Context]; 
Place: --W/nofoW" type = UserTerminal. Coordinate; 
Placeholder: -TlPStar- type = { 

mouseActions, keyOverrides, softKeys, keyboardSpeclfic, blackKeys, sideKeys, 

backstopSpecialFocus}; 
Point: -Display- procedure (window: Handle, point: Window.Place]; 
Pop: ~StarW/ndowS/)e//- procedure [popee: Handle] returns [Handle]; 
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PopOrSwap: -StarWindowSheH- type s {pop, swap}; 
PoppedProc: -StarWindowSheU- type = procedure [ 

popped: Handle, newShell: Handle, popOrSwap: PopOrSwap "pop]; 
PopTabie: -TlPStar- procedure [Placeholder, TIP. Table]; 
Popup: -PopupMenu" procedure [ 

menu: MenuData.MenuHandle, clients: Window. Handle, showTltle: boolean "true, 

place: Window.Place *LOOPHOLE{37777777777B]]; 
Post: -Attention" procedure ( 

s: XString. Reader, clear: boolean 'true, beep: boolean "false, 

blink: boolean "false]; 
Post: "MessageWindow- procedure [ 

window: Window.Handle, r: XString. Reader, clear: boolean "true]; 
PostAndConfirm: -Attent/on- procedure [ 

s: XString. Reader, clear: boolean tp.e, 

confirmChoices: ConfirmChoices xxx timeout: Process.Ticks "dontTimeout, 

beep: boolean "false, blink: BOOLEA^ false] 

returns [confirmed: boolean, timedOjt: boolean]; 
PostSticky: -Attention- procedure [ 

s: XString. Reader, clear: boolean tr_:, beep: boolean "false, 

blink: boolean "false]; 
PostSTRING: -MessageWindow- procedure [ 

window: Window.Handle, s: long st? ng, clear: boolean "true]; 
Power: -Xl/?ea/~ procedure [base: Numoer, exponent: Number] returns (Number); 
Prerequisite: -ProductFactoring- type = record [ 

prerequisiteSpec: boolean "false, option: Option]; 
printingLigatures: -XC/iar5et550~XCharSets.Sets = LOOPHOLE[240]; 
Privateltem: -MenuData- type = private record [ 

proc: MenuProc, 

nameWidth: natural, 

nameBytes: natural, 

body: select hasltemOata: boolean from 

FALSE = > [name: packed sequence computed cardinal of EnvironmentByte], 

TRUE = > [ 

item Data: long unspecified, 

name: packed sequence computed cardinal of EnvironmentByte], 

endcase); 

PrivateMenu: -MenuData- type ss private record [ 

zone: uncounted zone, 

swapltemProc: SwapltemProc, 

title: ItemHandle "nil, 

array: ArrayHandle "xxx, 

arrayAllocatedltemHandles: natural "0, 

itemslnMenusZone: boolean "false]; 
Problem: -SimpleTextFont- signal [code: ProblemCode]; 
ProblemCode: -SimpleTextFont- type = { 

badFont, clientCharacterCodesExhausted,clientCharacterBitsExhausted}; 
Proc: "L/ndo-TYPE = procedure [ 

undoProc: procedure [long pointer], destroyProc: procedure [long pointer], 

data: long pointer, size: cardinal "0]; 
Procedures: -ContainerSource- type = long pointer to ProceduresObject; 
ProceduresObject: -ContainerSource- type = record [ 

actOn: ActOnProc, 

canYouTake: CanYouTakeProc, 

columnCount: ColumnCountProc, 

convertltem: Con vert Item Proc, 

deleteltems: Delete Item sProc, 
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getLength: GetLengthProc, 

itemGeneric: ItemGenericProc, 

stringOfltem: StringOfltemProc, 

take: TakeProcJ; 
Product: -Proc/octfactor/ng- TYPE = cardinal [0.. 15]; 
Product: -ProductFactoringProducts- type = ProductFactoring.Product; 
Product: -ProductFactoringProductsExtras- type = ProductFactoring.Product; 
ProductOption: -ProductFactor/ng- TYPE = cardinal [0..271; 
propertySheetDefaultMenu: -PropertySheet- Menultems; 
prototypeCatalog: -8WSF/7erype$- NSFile.Type = 1; 
PublicZone: -MenuData- procedure returns [uncounted zone]; 
PurgeOldVersions: -Prototype- procedure [ 

type: NSFile.Type, current: Version, subtype: Subtype *0]; 
Push: -ff/ac/r/Ceys- PROCEDURE [keyboard Keyboard]; 
Push: -SoftKeys- procedure [ 

table: TlP.Table 'nil, notifyProc: TIP NotifyProc "nil, 

labels: Labels 'xxx, highlightedKey: i-^dinal 'nullKey, 

outlinedKey: cardinal *nullKey] retu= is [window: Window.HandleJ; 
push: -StarWindowShell- procedure [ 

newSheii: Handle, topOfStack: Handle 'LOOPHOLE[0], 

poppedProc: PoppedProc 'nil]; 
PushedMe: -StarWindowShellExtra- pp:cedure [pushee: StarWindowShell. Handle] 

returns [pusher: StarWindowShell. Handle]; 
PushedOnMe: -StarWindowShellExtra- procedure [pusher: StarWindowShell. Handle] 

returns [pushee: StarWindowShell. Handle]; 
PushTable: -TlPStar- procedure [Placeholder, TlP.Table]; 
PutProp: -Atom- procedure [onto: atom, pair: Pair]; 
Query: ~Se/ect/on- procedure [ 

targets: long descriptor for array cardinal of QueryElement]; 
QueryElement: -Selection^ type = record [ 

target: Target, enumeration: boolean 'false, difficulty: Difficulty "null]; 
Quote: -XToken- QuoteProcType; 

QuoteProcType: -XToken- type = procedure [c: XChar, Character] 

returns (closing: XChar. Character]; 
Reader: -XFormat" procedure [h: Handle "nil, r: XString. Reader]; 
Reader: -XString- type = long pointer to ReaderBody; 
ReaderBody: -XFormat- procedure [h: Handle "nil, rb: XString.ReaderBody]; 
ReaderBody: -XString- type = private machine dependent record [ 

context(0:0.. 15): Context, 

limit(1:0..15): cardinal, 

offset(2:0..15): cardinal, 

bytes(3:0..31): ReadOnlyBytes]; 
ReaderFromWriter: -XString- procedure [w: Writer] returns [Reader]; 
Readerlnfo: -XString- procedure [r: Reader] 

returns [context: Context, startsWith377B: boolean]; 
ReaderToHandle: -XToken- procedure [r: XString. Reader] returns [h: Handle]; 
ReaderToNumber: -XLReal- procedure [r: XString. Reader] returns [Number]; 
ReaderToNumber: -XString- procedure ( 

r: Reader, radix: cardinal "10, signed: boolean "false] 

returns (long integer]; 
ReadNumber: -XLReal- procedure [ 

get: procedure returns [XChar.Character], 

putback: procedure [XChar.Character]] returns [Number]; 
ReadOnlyBytes: -XString- type = long pointer to readonly ByteSequence; 



D-36 



Viewpoint Programmer's Manual 



D 



Rebuildltem: -'FileContainer5ourceExtra2~ procedure ( 
source: ContainerSource.Handie, item: ContainerSource.ltemindex]; 

Reconversion: -Selection" signal [target: Target, zone: uncounted zone] 
RETURNS (Vaiuel; 

ReconvertDuringEnumerate: -5e/ect/on- procedure [ 

target: Target, zone: uncounted zone * LOOPHOLE[01] returns [Value]; 

RefAny: -Atom- type = long pointer; 

referencedType: -flWSAttr/bote fypes- NSFiie.ExtendedAttributeType = 10401 B; 
RefPair: -Atom- type = long pointer to readonly Pair; 
refParentID: -SWSAttnbuterypes- NSFi I e.ExtendedAttributeType = 10403B; 
refparentTime: -flVVSAttr/bote fypes- NSFile.ExtendedAttributeType = 104058; 
RegisterClientKeyboards: -KeyboardKey- procedure [ 

wantSystem Keyboards: boolean 'true, 

SPECIALKeyboard: BlackKeys.Keyboard ^nil, 

keyboards: long descriptor for array cardinal of BlackKeys-KeyboardObject * 
xxx]; 

RegisterMessages: -XMessage- procedure [ 

h: Handle, messages: Messages, stringBodiesAreReal: boolean]; 
Relation: -XString- type = {less, equal, greater}; 
Release: -Context- procedure [type: Type, window: Window.Handle]; 
Remainder: -XLReal- procedure (a: Numoer, b: Number] returns [Number]; 
remoteName: -flVVSAttr/bt/tefypes- NSF le.ExtendedAttributeType = 10406B; 
Remove: -fi/ac/r/Cej^- procedure [keyboard: Keyboard]; 
Remove: -SoftKeys- procedure [windo\A< Window.Handle]; 
RemoveClientKeyboards: -KeyboardKey - procedure; 
RemoveOependency: -Event- procedure [dependency: Dependency]; 
RemoveFromSystemKey boards: -/Ceyfaoard/Cey- procedure [ 

keyboard: BlackKeys.Keyboard]; 
RemoveFromTree: -Window- procedure [Handle]; 
RemoveltemFromLine; -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, line: Line, repaint: boolean "true]; 
RemoveMenuitem: -Attention- procedure [item: MenuData Item Handle]; 
RemoveProp: -Atom- procedure [onto: atom, prop: atom]; 
Repaint: -FormWindow- procedure [window: Window.Handle]; 
RepaintFleld: -SimpleTextEdit- procedure [f: Field]; 
Replace: -StarWmdowShell Extra- procedure [ 

new: StarWindowShel I. Handle, old: StarWindowShell. Handle]; 
ReplaceChars: -SimpieTextEdit- procedure [ 

f: Field, firstChar: cardinal, nChars: cardinal, r: XString. Reader, 

endContext: XString. Context "LOOPHOLE[2S5], repaint: boolean *true]; 
replaceFlags: -Display- BitBltFlags; 
replaceGrayFlags: -Display- BitBltFlags; 
Replaceitem: -ContainerCache- procedure [ 

cache: Handle, item: cardinal, addData: AddOata] returns [handle: ItemHandle]; 
RepiacePiece: -XString- procedure [ 

w: Writer, firstChar: cardinal, nChars: cardinal, r: Reader, 

endContext: Context ^unknownContext]; 
RequestorData: ~Se/ecf/on- type « long pointer; 

ResetAllChanged: -FormWmdow- procedure [window: Window.Handle]; 
ResetCache: -ContainerCache- procedure [Handle]; 

ResetChanged: -FormWindow- procedure [window: Window.Handle, item: ItemKey]; 
ResetUserAbort: -TIP- procedure [Window.Handle]; 

ResolveBuffer: -SimpleTextDisplay- type = long descriptor for array [0..0) of 

cardinal; 

Restore: -FormWmdow- procedure [window: Window.Handle]; 
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Restore: -Selection- procedure [ j^l 

saved: Saved, mark: boolean "TRUf, unmark: boolean "true]; 
Result: -SimpleTextDisplay- TYPE = {normal, margin, stop}; 
ResultObject: -r/P-TYPE = record [ 
next: Results, 
body: select type: * from 
atom = > (a: atom], 
bufferedChar = > null, 
coords = > [place: Window. PI ace], 
int s > [i: long integer], 
key s > [key: KeyName, downUp: OownUp], 

nop = > NULL, 

string a > [rb: XString.ReaderBody], 
time = > [time: System. Pulses], 

endcase]; 

Results: -r/P- TYPE = long pointer to ResLitObject; 
ResultsWanted: -nPX- type = procedure [ 

window: Window.Handle, table: TIP.Tcole "nil, results: TIP.Results] 

RETURNS [wanted: boolean]; 
ReturnTicket: "Containee- procedure [ticr.et: Ticket]; 
ReturnToNotifier: -TIP- error [string: XS:-ing.Reader]; 
ReverseLop: -XString- procedure [ 

r: Reader, endContext: long pointer to Context, 

backScan: BackScanClosure 'xxxj retl*' s [c: Character]; 
ReverseMap: --XString- procedure [r: Reader, proc: MapCharProc] 

returns [c: Character]; 
Roadblock: -Undo- procedure [XString. Reader]; 
root: -BWSFileTypes- NSFile.Type = 10477B; 
Root: -Window- procedure returns [Handle]; 

Root: -XLReal- procedure [index: Number, arg: Number] returns [Number]; 

rootWindow: -Window- readonly Handle; 

Run: -XString- procedure [r: Reader] returns [run: ReaderBody]; 

Save: -FormWindow- procedure [window: Window.Handle]; 

SaveAndSet: -Selection- procedure [ 

pointer: ManagerData, conversion: ConvertProc, actOn: ActOnProc, 

unmark: boolean "true] returns [old: Saved]; 
Saved : -Selection- type [6]; 
Scan: -XString- procedure [ 

r: Reader, break: BreakTable, option: BreakCharOption] 

RETURNS [breakChar: Character, front: ReaderBody]; 
ScanForCharacter: -XString- procedure [ 

r: Reader, char: Character, option: BreakCharOption] 

RETURNS [breakChar: Character, front: ReaderBody]; 
ScrollData: -StarWindowShell- type = record [ 

displayHorizontal: boolean 'false, 

displayVertical : boolean 'false, 

arrowScroll: ArrowScrollProc "nil, 

thumbScroll: ThumbScroilProc 'nil, 

moreScroll: MoreScrollProc "nil]; 
SectionEnumProc: -OptionFile- type = procedure [section: XString. Reader] 

returns (stop: boolean "false]; 
Selectltem: -ContainerWindow- procedure [ jlll 

window: Window.Handle, item: ContainerSource.ltemlndex]; 
SelectReference: -StarDesktop- procedure [reference: NSFile.Reference] 

returns (ok: boolean]; 
Semipermanent: -BWSZone- procedure returns [uncounted zone]; 
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semipermanent: -BWSZone- uncounted zone; 

Services2: -ProductFactoringProductsExtras- Product = 8; 

Services: -Prodi/ctfactor/ngProdtJCts- Product a 1; 

Set: -Context- procedure [type: Type, data: Data, window: Window.Handle]; 
Set: -'Cursor- procedure [type: Defined]; 
Set: -Selection" procedure [ • 

pointer: ManagerData, conversion: ConvertProc, actOn: ActOnProc]; 
Set: -XChar- procedure [c: Character] returns [set: Environment. Byte); 
SetAdjustProc: -StarWindowShell- procedure [sws: Handle, proc: AdjustProc] 

RETURNS [old: AdjustProc); 
SetAtlChanged: -FormW/ndow- procedure [window: Window.Handle]; 
SetAttention: -TIP- procedure [ 

window: Window.Handle, attention: Attention Proc]; 
SetBackStopinputFocus: -77P- procedure [window: Window.Handle]; 
SetBltmapUnder: -Window- procedure [ 

window: Handle, pointer: LONG pointer mil, 

underChanged: UnderChangedProc 'n . 

mouseTransformer: MouseTransformer='oc "nil] returns [long pointer]; 
SetBodyWindowJustFits: -StarWindowShell- procedure. [ 

sws: Handle, yes: boolean]; 
SetBOOLEAN: -Atom/cProf/7e- procedure >tom: Atom.ATOM, boolean: boolean]; 
SetBooleanltemValue: -FormWindow- pp 3CEDURE [ 

window: Window.Handle, item: ItemKey, newVatue: boolean, 

repaint: boolean 'true]; 
SetBottomPusheeCommands: -StarWindowShell- procedure [ 

sws: Handle, commands: MenuData.MenuHandle]; 
SetCachedName: -Containee- procedure [ 

data: DataHandle, newName: XString. Reader]; 
SetCachedType: -Conta/nee- procedure (data: DataHandle, newType: NSFile.Type]; 
SetChanged: -FormW/ndow- procedure [window: Window.Handle, item: ItemKey]; 
SetCharTransiator: -TIP- procedure [table: Table, new: CharTranslator] 

returns [old: CharTranslator]; 
SetChlld: -W/ndow- procedure [window: Handle, newChild: Handle] 

returns [oldChild: Handle]; 
SetChoiceitemVaiue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: Choicelndex, 

repaint: boolean 'true]; 
SetCiearingRequired: -Window- procedure [window: Handle, required: boolean] 

returns [old: boolean); 
SetContainee: StarWindowShell- procedure [ 

sws: Handle, file: Containee.DataHandle); 
SetDecimalltemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: XLReal. Number, 

repaint: boolean 'true); 
SetDefaultlmplementation: -Containee- procedure [Implementation] 

RETURNS [Implementation]; 
SetDefauitOutputSink: --XFormat- procedure [new: Object] returns [old: Object]; 
SetDesktopProc: -IdleControl- procedure [ 

atom: Atom.ATOM, desktop: DesktopProc); 
SetDlms: -SimpleTextEdit- procedure [f: Field, dims: Window. Dims); 
SetDisplayBackgroundProc: -StarDesktop- procedure [procedure [Window.Handle]]; 
SetOispiayProc: -Window- procedure [Handle, DisplayProc] 

RETURNS [DisplayProc]; 
SetFixedHelght: -SimpleTextEdit- procedure [f : Field, fixedHeight: boolean]; 
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SetFlushness: -Form Window- procedure [ 

window: Window. Handle, item: ItemKey, new: Flushness] 

RETURNS (old: Flushness]; 
SetFlushness: -SimpleTextEdit - procedure [ 

f: Field, new: SimpleTextDispiay.Flushnessl 

RETURNS [old: SimpleTextDisplay. Flushness]; 
SetFont: -SimpleTextEdit- procedure ( 

f: Field, font: SimpleTextFontMappedFontHandle 'nil]; 
SetGlobalChangeProc: -Form Window-- procedure ( 

window: Window.Handle, proc: GlobaiChangeProc] 

returns (old: GlobaiChangeProc]; 
SetGreeterProc: -IdieControl- procedure [new: GreeterProcJ 

RETURNS [old: GreeterProc]; 
SetHost: -StarWindowSheil- procedure [sws: Handle, host: Handle] 

RETURNS [old: Handle]; 
Setlmplementation: -Containee- procedu== [NSFile.Type, Implementation] 

RETURNS [Implementation]; 
Setlmplementation: --Undo- procedure [Imolementation] returns [Implementation]; 
SetlnputFocus: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, beforeChar: cardinal M77777B]; 
SetlnputFocus: -SimpleTextEdit- procedure ( 

f: Field, beforeChar: cardinal '177777B]; 
SetlnputFocus: -f/P- procedure [ 

w: Window.Handle, takeslnput: booleal, newlnputFocus: LosingFocusProc 'nil, 

clientData: long pointer 'nil]; 
SetintegerltemVaiue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: long integer, 

repaint: BOOLEAN "true]; 
SetlsCloseLegalProc: -StarWindowSheil- procedure [ 

sws: Handle, proc: IsCloseLegalProc]; 
SetitemBox: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, box: Window.Box]; 
SetltemNameWidth: -MenuData- procedure [item: ItemHandle, width: cardinal]; 
SetltemWidth: -FormWindow- procedure [ 

window: VVindow.Handle, item: ItemKey, width: cardinal]; 
SetKeyboard: -KeyboardKey- procedure [keyboard: BlackKeys. Keyboard); 
SetLimitProc: -StarWindowSheil- procedure [sws: Handle, proc: LimitProc] 

returns (old: LimitProc]; 
SetLONGlNTEGER: -Atom icPro file- procedure [ 

atom: Atom.ATOM, int: long integer]; 
SetManager: --f/P- procedure (new: Manager] returns [old: Manager]; 
SetMark: -ContainerCache- procedure [cache: Handle, index: cardinal] 

RETURNS [mark: Mark]; 
SetMiddlePusheeCommands: -StarWindowSheil- procedure [ 
• sws: Handle, commands: MenuData. MenuHandle]; 
^etMode: -TIPStar- procedure ( * 

mode: Mode, modeChangeProc: ModeChangeProc 'nil, 

clientData: long pointer *nil] returns (old: Mode]; 
SetMultipleChoiceitemValue: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, 

newValues: long descriptor for array cardinal of Choicelndex, 

repaint: boolean "true]; 
SetName: -StarWindowSheil- procedure [sws: Handle, name: XString. Reader]; 
SetNamePicture: StarWindowSheil- procedure [ 

sws: Handle, picture: XString, Character]; 
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SetNextOutOfProc: -Form Window- procedure ( 

window: Window. Handle, Item: ItemKey, nextOutOfProc: NextOutOfProc] 

RETURNS [old: NextOutOfProc]; 
SetNotifyProc: -r/P- procedure (window: WIndow.Handle, notify: NotifyProc] 

RETURNS loldNotify: NotifyProc]; 
SetNotifyProcForTabie: -TIP- procedure [table: Table, notify: NotifyProc] 

RETURNS (oldNotify: NotifyProc]; 
SetParent: -Window^ procedure [window: Handle, newParent: Handle] 

RETURNS (oldParent: Handle]; 
SetPlace: -SimpleTextEdit- procedure [f: Field, place: Window.Place]; 
SetPreferredDims: "StarWindowShell- procedure [ 

sws: Handle, dims: Window.Dims]; 
SetPreferredlnteriorOims: -'StarWindowShellExtra2-- procedure [ 

sws: StarWindowShell.Handle, dims: Window.Dims]; 
SetPreferredPlace: -StarWindowShell-- pro'=dure [ 

sws: Handle, place: Window.Place]; 
SetReadOnly: -Form Window- procedure [ 

window: Window.Handle, item: ItemKey readonly: boolean] 

RETURNS [old: boolean]; 
SetReadOnly: -S/mp/erextfd/t- procedure Field, readonly: boolean] 

RETURNS [old: boolean]; 
SetReadOnly: -StarWindowShell- procedl = = [sws: Handle, yes: boolean]; 
SetRegularCommands: -StarWindowSheli- procedure [ 

sws: Handle, commands: MenuData.Men jHandle]; 
Sets: -XC/iarSets- type = machine dependen-{ 

latin, firstUnusedl, lastUnused1(32), jisSymboM, jisSymbol2, extended Latin, 

hiragana, katakana, greek, Cyrillic, firstUserKanjil, lastUserKanji1(47), 

firstLevel 1 Kanji, lastLevel 1 Kanji(79), fi rst Level 2Kanji, lastLevel2Kanji( 1 15), 

jSymbol3, firstUserKanji2, lastUserKanji2(126), firstUnused2, 

lastUnused2(160), firstReservedl, lastReserved 1(223), arable, hebrew, 

firstReserved2, lastReserved2(237), genera I Symbols2, generalSymboisI, 

first Rendering, lastRendering(2S3), userOefined, selectCode}; 
SetScrollData: --Star W/ndowS/?e//- procedure [sws: Handle, new: ScrollData] 

RETU RNS [old : Scrol I Data] ; 
SetSelection: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, firstChar: cardinal *0, 

lastChar: cardinal '177777B]; 
SetSelection: -SimpieTextEdit- procedure [ 

f: Field, firstChar: cardinal '0, lastChar: cardinal M77777B]; 
SetShowKeyboardProc: -KeyboardKey- ?>rocedure [ShowKeyboardProc]; 
SetSibling: -Window- procedure [window: Handle, newSibling: Handle] 

RETURNS (oldSibling: Handle]; 
SetSleeps: -StarWindowSheli Extra- procedure [ 

sws: StarWindowShell.Handle, sleeps: boolean] returns [old: boolean]; 
SetSource: -ContainerWindow- procedure [ 

window: Window.Handle, newSource: ContainerSource.Handle] 

returns [oldSource: ContainerSource.Handle]; 
SetState: -StarWindowSheli- procedure [sws: Handle, state: State]; 
SetStreakSuccession: -FormWindow- procedure [ 

window: Window.Handle, item: ItemKey, new: StreakSuccession] 

returns [old: StreakSuccession]; 
SetStreakSuccession: --S/mp/efextEd/t-- procedure [ 

f: Field, new: SimpleTextDisplay. StreakSuccession] 

returns [old: SimpleTextDisplay.StreakSuccession]; 
SetString: -Atom icPro file- procedure [ 

atom: Atom.ATOM, stnng: XString. Reader, immutable: boolean 'false]; 
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SetSwapitemProc: -MenuData- procedure (menu: Menu Handle, new: SwapltemProc] 

RETURNS (old: SwapltemProc]; 
SetTable: -TIP- procedure [window: Window. Handle, table: Table] 

RETURNS (oldTable: Table]; 
SetTableAndNotlfyProc: -TIP- procedure ( 

window: Window. Handle, table: Table 'nil, notify: NotifyProc 'nil]; 
SetTabieLink: -TIP- procedure (from: Table, to: Table] returns (old: Table]; 
SetTableOpacity: -TIP- procedure (table: Table, opaque: boolean] 

returns (oldOpaque: boolean); 
SetTabStops: -FormWindow- procedure ( 

window: Window. Handle, tabStops: TabStops]; 
SetTextltemValue: -Form W/nc/ow- procedure [ 

window: Window.Handle, item: ItemKey, newValue: XString. Reader, 

repaint: boolean 'true]; 
SetTopPusheeCommands: StarWindowSheil- procedure ( 

sws: Handle, commands: MenuData.Menu Handle]; 
SetTransitlonProc: -StarWindowSheil- procedure ( 

sws: Handle, new: TransitionProc] returns ".old: TransitionProc]; 
SetUseBadPhosphor: -Window- procedure Handle, boolean] returns [boolean]; 
SetUserAbort: -TIP- procedure [Window.Handle]; 
SetValue: -SimpleTextEdit- procedure [ 

f: Field, string: XString. Reader, repaint: boolean 'true]; 
SetVlsibility: -FormWindow- procedure ( 

window: Window.Handle, item: ItemKey, visibility: Visibility, 

repaint: boolean 'true]; 
SetWindowitemSize: -FormWindow- procedure ( 

window: Window.Handle, windowltemKey: ItemKey, newSize: Window.Dims]; 
Shell EnumProc: -StarW/ndowShe//- TYPE = =rocedure [sws: Handle] 

RETURNS (stop: BOOLEAN 'FALSE]; 

ShellFromChild: StarWindowSheil- procedure (child: Window.Handle] 

RETURNS [Handle]; 
ShellType: -StarWindowSheil- type = mach ne dependent{ 

regular, keyboard, psheet, attention, static, last(15)}; 
Shift: -Display- procedure ( 

window: Handle, box: Window.Box, newPlace: Window.Place]; 
ShiftState: -KeyboardWindow- ^ype = {None, One, Two, Both}; 
ShortLifetime: -BWSZone- procedure returns [uncounted zone); 
shortUfetime: -BWSZone- uncounted zone; 
ShowKeyboardProc: -KeyboardKey- type = procedure; 
Signal: -Containee- signal ( 

msg: XString. Reader 'nil, error: error *nil, errorOata: long pointer 'nil]; 
Signal: -ContainerSource- signal [ 

code: ErrorCode, msg: XString.Reader "nil, error: error 'nil, 

errorOata: long pointer 'nil]; 
SimpleDestroyProc: .-Context- Destroy ProcType; 
Sin: -XLReal- procedure [radians: Number] returns [sin: Number]; 
SizeCoiumn: -FileContainerSource- procedure 

returns [multipleAttributes ColumnContentslnfo]; 
Skip: -XToken- procedure ( 

h: Handle, data: FilterState, filter: FilterProcType, 

skiplnClass: boolean 'true]; 
SkipMode: -Xro/cen-TYPE = {none, whiteSpace, nonToken}; 
SleepOrDestroy: -StarWindowSheil- procedure [Handle] returns [Handle]; 
Slide: -Window- procedure [window: Handle, newPlace: Place]; 
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SiideAndSize: -Window- procedure [ 

window: Handle, newBox: Box, gravity: Gravity 'nwj; 
SlideAndSizeAndStack: -Window- procedure [ 

window: Handle, newBox: Box, newSibling: Handle, newParent: Handle "nil, 

gravity: Gravity 'nw]; 
SlideAndStack: -Window- procedure ( 

window: Handle, newPlace: Place, newSibling: Handle, newParent: Handle "imilJ; 
SmallPictureProc: -Containee- type = procedure [ 

data: DataHandle "nil, type: NSFile.Type ignoreType, 

normal Or Reference: PictureState] returns [smallPicture: XString. Character]; 
SocketNumber: -XFormat- procedure [ 

h: Handle "nil, socketNumber: System.SocketNumber, format: NetFormat]; 
SortOrder: -XString- type = machine dependent{ 

standard, Spanish, Swedish, danish, firstPree, null(255)}; 
SourceModifyProc: -ContainerWindow- tvp; s procedure [ 

window: Window.Handle, source: Contair^erSource. Handle] 

returns (changelnfo: ContainerSource.Cha-gelnfo]; 
spares: -SWSAttr/buterypes- cardinal = 20 
Speciallndex: -XLReai-jyPB = natural; 
Spinnaker: -ProductFactohngProducts- Procjct = 2; 
SqRt: -XLReal- PROCEDURE [Number] returns [Number]; 
Stack: -Window- procedure [ 

window: Handle, newSibling: Handle, newParent: Handle "nil); 
StandardClose: -StarW/ndowS/)e//- procedu== [sws: Handle] returns [Handle]; 
StandardCloseAII: -StarV1//ndowS/)e//-- procedure [sws: Handle] returns [Handle]; 
StandardCloseEverything: -StarWindowShell- procedure 

returns [notCIosed: Handle]; 
StandardFilterState: -Xro/cen- type = array [O/.I] of unspecified; 
Standard Li mitProc: -StarWindowShell- LimitProc; 
Star: -ProductFactoringProducts- Product = 0; 
State: -StarWindowShell- type = machine dependent{ 

awake, sleeping, dead, last(7)}; 
StatusOfFill: -ContainerCache- procedure [cache: Handle] 

returns [CacheFillStatus]; 
StopOrNot: -XStr/ng- type = {stop, not} "not; 
Store: -Cursor- procedure [h: Handle]; 
StoreCharacter: -Cursor- procedure [c: XChar.Character]; 
StoreNumber: -Cursor- procedure [n: cardinal]; 

StoreTable: -TIPStar- procedure [Placeholder, TIP.Table] returns [TIP.Table]; 
StreakNature: -XChar- type = {leftToRight, rightToLeft}; 
StreakSuccession: -FormWindow- type = SimpleTextDisplay.StreakSuccession; 
StreakSuccession: -S/mp/efextD/sp/ay- TYPE = { 

leftToRight, rightToLeft, fromFirstChar}; 
StreamObject: -XFormat- procedure [sH: Stream. Handle] returns [Object]; 
Stream Proc: -XFormat- FormatProc; 

StreamToHandle: -Xro/cen- procedure [s: Stream. Handle] returns (h: Handle]; 
String: -XFormat- procedure [h: Handle "nil, s: long string]; 
StringArray: -XMessage- type = long descriptor for array cardinal of 

XStri ng. ReaderBody ; 
StringfntQBuffer: -SimpleTextDisplay- procedure [ 

string: XString.Reader, bufferProc: BufferProc, lineWidth: cardinal ^UllllB, 

wordBreak: boolean "true, StreakSuccession: StreakSuccession "fromFirstChar, 

font: SimpleTextFontMappedFontHandle "nil] 

returns [lastU'neWidth: cardinal, result: Result, rest: XString. ReaderBody]; 
String! ntoWindow: -SimpleTextDisplay- procedure [ 

string: XString.Reader, window: Window.Handle, place: Window.Place, 
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lineWidth: cardinal "177777B, maxNumberOfLines: cardinal 

lineToLineDeltaY: cardinal '0, wordBreak: boolean *true, 

flags: BItBlt.BitBltFlags UOOPHOLE(42000B]J 

RETURNS (lines: cardinal, lastLineWidth: cardinal]; 
StringOfltem: -ContainerSource- StrlngOfltemProc; 
StringOfltemProc: -ContainerSource- type = procedure [ 

source: Handle, itemlndex: Itemlndex, stringlndex: cardinal] 

RETURNS [XString.ReaderBody]; 
StuffCharacter: -TIP- procedure [ 

window: Window.Handle, char: XString.Character] returns [boolean]; 
Stuff CurrentSeiection: -TVP- procedure (window: Window.Handle] 

returns (boolean); 

StuffResuits: -r/P- procedure (window: Window.Handle, results: Results); 
StuffSTRING: -TIP- PROCEDURE (window: Window.Handle, string: long string) 

RETURNS (boolean); 

StuffString: --r/P-- procedure (window: Windcw.Handle, string: XString. Reader] 

RETURNS (boolean); 

StuffTrashBin: -TIP- procedure (window: Wi-dow.Handle) returns (boolean); 
Subtract: -XLReal- procedure [a: Number, b .umber) returns (Number); 
Subtractltem: -MenuData- procedure [menu VIenuHandle, old: ItemHandle); 
SubtractPopupMenu: -StarWindowShell- p^c :edure [ 

sws: Handle, menu: MenuOata.MenuHand'e); 
Subtype: -Prototype- type = cardinal; 

Swap: "8/ac/f/Ceys~ PROCEDURE (old: Keyboara new: Keyboard); 

Swap: -Cursor- procedure (old: Handle, new: Handle); 

Swap: -SoftKeys- procedure ( 

window: Window.Handle, tabie: TIP. Table nil, 
notifyProc: TIP. Notify Proc "nil, labels: Labels *xxx, 
highlightedKey: cardinal "nullKey, outlinedKey: cardinal 'nullKey); 

Swap: -StarWindowShell- procedure ( 

new: Handle, old: Handle, poppedProc: PoppedProc 'nil); 

SwapExistingFormWindows: -PropertySheet- procedure [ 

shell: StarWindowShell. Handle, new: Window.Handle, apply: boolean 'true, 
newMenultemProc: MenultemProc 'nil, newMenultems; Menultems 'LOOPHOLE[0), 
newTitie: XString. Reader 'nil, newAfterTakenDownProc: MenultemProc 'nil) 
RETURNS [old: Window.Handle); 

SwapFormWindows: -PropertySheet- procedure [ 

shell: StarWindowShell. Handle, newFormWindowltems: 

FormWindow.MakeltemsProc, 

newFormWindowltemsLayout: FormWindow.LayoutProc 'nil, apply: boolean 'true, 
destroyOld: boolean 'true, newMenultemProc: MenultemProc 'nil, 
newMenultems: Menultems 'LOOPHOLE(O), newTitle: XString. Reader 'nil, 
newGlobalChangeProc: FormWindow.GlobalChangeProc 'nil, 
newAfterTakenDownProc: MenultemProc 'nil) returns (old: Window.Handle); 

Swapltem: -MenuData- procedure [ 

menu: MenuHandie,pld: ItemHandle, new: ItemHandle); 

SwapltemProc: --/Went/Data- type = procedure [ 

menu: MenuHandle, old: ItemHandle, new: ItemHandle); 

SwapMenultem: -Attention- procedure ( 

old: MenuData. ItemHandle, new: MenuData.ltemHandle); 

Switches: -XToken- FilterProcType; 

SyntaxError: -Xfo/cen- signal [r: XString. Reader); 

systemFileCatalog: ~aWSF//erypes~ NSFtle.Type = 104768; 

systemFontHeight: -SimpleTextDisplay- readonly cardinal; 
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Table: -77P- TYPE = LONG POINTER TO TableObject; / -/l", ,! 

TableError: -r/P- TYPE = {fileNotFound, badSyntax}; 

TableObject: -r/P- type; ^.n 

TabStops: -Form W/ndow- TYPE * RECORD [ 

variant: select type: TabType FROM . / ' . 

fixed = > [interval: cardinal], , ' 

vary = > (list: long descriptor for array cardinal of cardinal],! ; 
enocase]; 

TabType: -FormWindow- type = {fixed, vary}; 
Take: -ContainerSource- TakeProc; 

TakeNEXTKey: -Pom? W/ndow~ procedure (window: Window. Handle, item: ItemKey); 

TakeProc: -ContainerSource-- type = procedure [ 

source: Handle, copyOrMove: Selection.CopyOrMove, 
afterHint: Itemlndex "nullltem, withinSameSource: boolean 'false, 
changeProc: ChangeProc 'nil, changeProcData: long pointer "nil, ..^ 
selection: Selection. Con vert Proc 'nil] RETURr.s [ok: boolean]; 

Tan: -XiReal- procedure [radians: Number] ^e-urns (tan: Number]; 

Target: -Se/ect/on~ TYPE = machine dependen"{ 

window, shell, subwindow, string, length, position, integer, interpressMaster, 
file, fileType, token, help, keyboard, interscr otScript, interscriptFragment, 
serializedFile, name, firstFree, last(1023)}; 

textFlags: -0/sp/ay~ BitBltFlags; 

TextHintAction: -FormWindow- type = {replace, append, nil}; ^' 
TextHintsProc: -Form M//ndow~ type = procec.re( 
window: Window. Handle, item: ItemKey] 

RETURNS ( / ' 

hints: long descriptor for array cardinal : f XString.ReaderBody,. 
%ir^ freeHints: FreeTextHintsProc, hintActlon: TextHintAction 'replace]; 

ThumbFlavor: -StarWindowShell-TypE a {downClick, track, upCiick}; 
ThumbScrollProc: -StarW/ndowS/ie//- TYPE = procedure [ 

sws: Handle, vertical:- boolean, flavor: ThumbFlavor, m: integer, 
outOfN: INTEGER]; 
Ticket: -Containee- type (2J; 
timeOniy: -XTime- XString. Reader; 

TIPResults: SimpleTextEdit- procedure (f: Field, results: TIP. Results] 

RETURNS [tooklnputFocus: boolean, changed: boolean]; 
Total OrPartial: -Conta/nerSoufce- type a {total, partial}; 
Trajectory: -Display- procedure [ 

window: Handle, box: Window. Box 'xxx, proc: Trajectory Proc, 

source: long pointer 'nil, bpl: cardinal '16, height: cardinal '16, 

flags: BitBltFlags "bitFlags, missesChildren: boolean 'false, 

brick: Brick 'xxx]; 
Trajectory Proc: -Display- type = procedure [Handle] 

returns [Window.Box, integer]; 
Transit! onProc: -StarWindowShell- type = procedure [ 

sws: Handle, state: State]; 
Trapezoid: -0/sp/ay- TYPE = RECORD ( 

x: Interpolator, y: integer, w: Interpolator, h: natural]; 
TreatNumbersAsi -XTime- type = { 

dayMonthYear, monthOayYear, yearMonthDay, yearOayMonth, dayYearMonth, 

month YearOay}; 

TrimBoxStickouts: -Window- procedure [window: Handle, box: Box] returns [Box]; 
TTYObject: -XPofma^- procedure (h: TTY. Handle] RETURNS^ tpbject]; 
TTYProc: -Xformat-^ FormatProc; ' 
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Type: -Context- TYPE = MACHINE depi-ndent{ > 

all, firstJastAllocated(37737B). last(37777B)}; 
Type: -"Cursor^ TYPE = MACHINE dependent{ v, 

blank, bullseye, confirm, ftpBoxeSp hourGlass, lib, menu, moyseRed, pointDown, 
PQ,^ppintLeft;pointRight, pointUp, questionMark, scrollDown, scrollLeft, 

scroll LeftRight, scrollRight, scrollUp, scrollUpDown, textPointer, 

groundedText, move, copy, sameAs, adjust, row, column, iast(255)}; 
UnderChangedProc: -Window- type = procedure [Handle, Qoya]; 
Unintelligible: -Xr/me- ERROR (vicinity: cardinal]; 
UniqueAction: ~Se/ect/on- procedure returns [Action]; 
UniqueTarget: Selection- procedure returns [Target]; / , , ; 
UniqueType: -Context- procedure returns [type: Type];, .^--^c : 
UniqueType: '-Cursor- procedure retjjrns [Type]: - ~ 
Units: ~l/n#tConversion- TYPE = machine qePE:NDE;NT{ , ; 
j,/, inch.^mm, cm, mica, point, pixel, pica, dIdotPoint, cicero, 

seventySecondOfAnlnchJast(15),}:;>.>'i< -t^jji- - > 
unknownContext: ~X5tr/ng- Context; r \N 

UnmapFont: -S/mp/erextFontfxtra- PROCEpuRi !SimpleTextFont. Mapped FontHandlej; 
Unpack: -XTime- PROCEDURE ( : . 

time: System.GreenwichMeanTime "default" me, Itp: LTP "useSystem] 

RETURNS [unpacked: Unpacked]; : - . .0 '; 

Unpacked: -Xr/me- type = record ( 

year: [0..4070B1, 

month: [0..1 1], c^- i ^ - 

day:[0..311, , ,,nc .r . y 

hour: [0..23], a-i^oicr i uc ' _ 

minute: [0.. 59], ; : .C£ ^ : r - j^-v 

;i5econd:.[0..:591, ■ vvu^:v v: ..- :.jr:t.. - ■ 

weekday: (0..6], - : - . ^ : - ■ 

[y^ndSt: boolean^ 

zone: System. LocalTimeParameters]; 
UnpostedSwapltemProc: -MenwOata- SwapltemProc; 
UnsignedDecimalFormat: -XFormat- NumberFormat; 
.;/UntefminatGdQuote:-Xro/cen- signal; 

; Update: -ContainerWindow— procedure (window: Window. Handle]; 

Uppercase: -XChar- procedure (c: Character] returns (Character]; 
s^useGMT: -XTVme-useThese LTP;: - 
UserAbort: -TIP- procedure [Window. Handle] returns [boolean]; 
userPassword : -StarDes/f top- Atom .atom; . 
useSystem: -XT/me- useSystem LTP; ; r in- 

valid: -Window- PROCEDURE [Handle] returns [boolean]; 
Validate: -Window- procedure (window: Handle]; i 
ValldateReader: -XStr/ng- procedure (r: Reader]; -r 
VaiidateTree: -IV/nofow- procedure [window: Handle "rootWindow]; 
ValidExponent: -XZ./?ea/~ TYPE = [-51 2.. 511]; 
Value: -Selection- type = record ( 

value: long pointer, 

ops: long pointer to ValueProcs "nil, 

context: long unspecified "OJ; 
ValueCopyMoveProc: -Se/ect/on~TYPE = procedure [ 

v: ValueHandle, op: CopyOrMove, data: long pointer]; 
ValueFreeProc: -Selection- TypE - procedure (v: ValueHandle]; 
ValueHandle: -Selection- type = long pointer to Value; 
ValueProcs: -Selection- type = record ( 

free: ValueFreeProc "nil, copyMove: ValueCopyMoveProc 'nil]; 
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VaniHaArrowScroll: --Star\^frtddwS?)e^- ArrowScrollProt?*'^^*^-- :sqvT 
vanillaContext: -XString- Contei(tr ' ^ - ' '''^ 
vanillaScrollData: --StarVI//ncifdwS/je//~ScrollData; "^- ^or -O - sqyT 
Vani I laThumbScrol I > -StarWindowShell- Thum bScrol I Proc;" ^ ^ 
version ?~fiWSAttr/i3ute rypes-^ NSFi le. ExtendedAttrlbuteTypie s^"^ TOeOB; 
Version'f~Protot/pe~ TYPE s '(Ordinal; - ■ r ini; : f J'lcr:j? 

VersiohCoiufnn: -FUeContainerSourceExtra-- procedure * 2 ^.3r r -s^ 

RETURNS [attri bute Fi I eContai nerSou rce. Col u m nContentsInf bif 
Viewpoint: -ProductFactoringProducts^-Product = 5; - iis:'>!'SJfi.nU 
ViewPointApps: UPrddoctfacfor/ngProdi/cts--' Product- = 6;^"^* 
Visibility: --FormWindoW''yypB ^-{vrsible, invisible, invisibleGThost}) *^ 
WaitSeconds: -T/P- procedure [seconds: cardinal]; -qv - -^uot-^U 

When : -StarWindowSheU- jy^t' «" {before, after},'- ^ - ; - " ♦ - ~ 
White: -O/sp/ay-- PROCEDtiREf - = .^-v- -no. v. . c' n -- 2;;rsw' 

window: Handle^ boxr Window. Box; bounds:'Window.BoxH'and1e 'nil]; 
WhiteSpace: -XToken- FilterProcType; ^ .'. ^ . - - v&i 
WordsForBitmapUnder: -Window- procedure v-vindow: Handle] returns [cardinal]; 
Writer: --XStr/hg- type s long pointer to WrH^rSodV;" • " ' ' * ' 
WriterBody: -XStr/ng- type = private machine o=pendent record f^'^^'^'*' 
context(0:0.. 15): Context, rmrr-,.. ,-: v.' ^-.-^-.uy. .r-m: 
limit(1:0..15): cardinal. ;i a^.. ^:>-':n^ >.:^ j-3;^ 

offset(2:0.. 15): CARDINAL, . - -^r-'' >^ - :c?^ ^^~anU 

bytes(3:0..31): Bytes, : to:...: -.b-v 

maxLimit(5:0.. 15): cardinal, • 
endContext(6:0.. 15): Context, : - '^^^ 

zone(7:0..31): uncounted zone]; ,^ '^^^^^ 

Writer Body FromBlock: -XString- procedure [ ' " ^ 

block: Environment.Block, inUse: cardinal O] returns [WriterBody]; 
WriterBodyFromNSString: -XString- procedure [ ^ ' ) ^'-^ - 

s: NSString.String, homogeneous: boolean '=alse] returns [WriterBody]; 
WriterBodyFromSTRlNG: --XString-- PROCEDURr['i'^ '--^ '" ^^'^ .' '"'^^^ 

s: long string, H<5m6geneous: boolean 'false] Returns [Wrii^erBodyr;'*^' 
Writerlnfo: --XStAmg-- procedure [w: Writer] " ' - ' ■•^'■'"^■^'^■■^ 

returns [unused: cardinal, endContext: Context, zone: uNCdlli?3T¥D zo'ne]; 
WriterObjectJ -XFormat-^ procedure [w: XString. Writer] returns [Object]; 
WriterProo --XFormat-- FormatProc; - .a- ■•:^Q:J 

XFormatObject: -MessageWindow- pRocEDURi [windbvvY V^tndow.Haindle] 

RETURNS^fXFormatiObjectF; ' ^ -v,;!. , : - V'- ; vdA-^i^U 
xorBoxFlags: -0/sp/ay~ BitBltFlags; "^oiA - c,o^ jC^h : x\:- ^f^-^f .j 
xorFlags: -Display- BitBltFlags; ' j - : - : tv: t?v?«^?j 

xorGrayFlags: -O/sp/ay-^ BitBltFlags; - --o v^ -Vv. ; .V 

zero: -XL/?ea/- Number; - ^ ^ t;^:'^":^"*^^ 

Zone: -Undo- procedure returns (uncounted zone]) ^s^*';: *-?''* . - s?*'' 

!.■•• ' s f;V O - ; .I' >ci " j,? ) . ■r<«^ 

1 3?^L)a^3Cy"- - ."^jf'^C- .X.. ^:.vo?v^vrvo3v V- 

■rr-ViiO'". ":''0J i>* ■" '"^ "sr:- :C0 3iO'^^'~?»LUn - 

■ -nDC-::>^\e^- lED'D'i'^SUJ . 
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